I've been caught by this time and time again so it's time I blogged about it. My Ghost blog is running on Azure Web Apps and it usually runs flawlessly, unless I do something stupid to break it. And since I like shiny new things, this happens quite frequently because I like to upgrade as often as I can.
However, upgrading my blog hasn't proved that easy or smooth as I would like it to be because there's a good chance I may miss a step or 2. So the best way to ensure that this doesn't happen again is to blog about it. So how does one upgrade their Ghost blog to the latest version?
Preparation
This is the most important step!! Ensure that your have a GOOD backup of your website on Azure. This way, if anything goes wrong, you can easily restore your latest backup and carry on with other things until you feel brave to attempt the upgrade again.
Perform that backup NOW! Go on, I'll wait...
Next we need to get the latest version of your blog from source control. If you don't have your blog code checked in, now is the time to do it. You may need to revert your changes if things go south, so make sure you use some sort of source control before applying any changes. Again, go on, I'll wait. With the Azure backup and source control in place, we are ready to progress. Download the latest code directly from [Ghost](https://ghost.org/download/" target="_blank). Unzip it somewhere handy. Back to source control, on your local branch, delete the following files and folders:
- Core (folder)
- node_modules (folder)
- GruntFile.js
- index.js
- npm-shrinkwrap.json
- package.json
From the unzipped folder you downloaded earlier, paste the files and folders we just deleted. Next run:
npm install --production
This will install a number of npm packages and you need to ensure it completes without errors. If there are any errors, you'll need to resolve them before you progress.
NOTE: The current version of Ghost requires Node 4.x.x and won't work with 5.x.x
If npm install completes successfully, you can test the site locally by running npm start. To ensure that everything works as expected, open the browser and navigate to /. If you're able to navigate and see your blog, we're in business! Now we can deploy our site to Azure.
Open the Azure portal and STOP your site. I like to deploy my site over FTP as I have exact control on which files are changed. Before deploying the new code, I delete the necessary files and folders in the same way we did earlier on when deploying locally. The fastest way to delete these files is through the Azure Kudu management portal. If you don't know about it, you're in for a treat. You can access it by navigating to the following URL:
https://
For reference, my site's Kudu portal is at https://cmatskas.scm.azurewebsites.net
Choose between the CMD or PowerShell debug console and navigate to the root of your site. Delete the files and folders we identified earlier.
Use an FTP console to upload the new files and folders apart from node_modules. This folder will be recreated when we run the npm install command in the debug console in Kudu. Once the file copy's complete, run the following commands:
npm cache clean
npm install --production
Once again, ensure that the install completes without errors. If there are any errors, something went wrong. You may want to run the commands again as I found this to resolve the problem, sometimes.
If you're successful, you can run the following command:
npm start
This could also highlight any potential issues. If there are none, go to the Azure Portal and start the website. Navigate to your site's URL, cross your fingers and hope for the best. IF you see a blank/white page, make sure that the node process is running by checking the Process Explorer in Kudu and that your site's started successfully in the portal. Try to restart the site and see if that resolves the problem. If not, roll your changes back by restoring the backup (first ever step) and restart your site. If you wish to troubleshoot further, you can check the logs for any potential issue and contact the Ghost team on Slack, in hope that you can find someone to help you. The community is generally quite active so you should be able to get help at a reasonably short time.
I hope this helps you the next time you get stuck. I believe that overall this post should cover most scenarios but I will update it with more information if I come across any other issues. And as always, feel free to let me know if I missed something.
Happy blogging!