Ghost Upgrade

Software changes fast in the modern world and keeping up-to-date can be difficult. Having left this site on an old version for over a year it needs to get some attention now.

This post may help those in a similar position and act as simple steps to follow for my self in the future. I am upgrading Ghost from version 2.1.3 to 3.8.0. This is quite a jump since I have left it for so long and results in a few additional steps that should not normally be necessary.

Backing Up

Before doing any work on your server it is worth backing everything up so that you can recover in case of a big mistake. I have several back-out plans for this upgrade, one which protects the content served in Ghost, another that will restore the entire server to an earlier state, and a final plan that simply backs up the files and folders used by Ghost.

The nuclear back-out option will be to restore the server to an earlier state. My server is hosted on Digital Ocean, so I can use the Snapshot service to take a point in time copy of everything. One downside to this is that it needs the server to be turned off before it can start. Another is that there is a cost incurred while the backup is kept.

Before diving in, I used some of the analytics provided in my CDN (content delivery network) provider, CloudFront. This helped determine a period of low use during the day. Taking the snapshot took about five minutes of downtime for my server, which is of a small size. Because I use CloudFront, the site did not go down during this time; a cached version of the blog was shown during the backup.

This upgrade is going to involve upgrading operating system files as well as the Ghost installation. If I do need to back-out, it may make sense to do a fresh install of Ghost and import the content, rather than restore from the snapshot. It all depends on what goes wrong. Having different options for reverting makes sense.

Therefore I also exported as much data from Ghost as possible. Not everything is exportable from the interface so here are the steps I took.

Code injection

My posts uses code injection to show syntax highlighting in code blocks. From the Code injection menu in Ghost Admin, I simply copied what is there into a local text file.

Content

The Labs section of Ghost Admin has a button that allows all content to be downloaded in one click. This will contain all posts and static pages but not images.

Images and other files

To backup the entire Ghost installation folder, I connected to the server and ran the following (changing “ghost” for the folder where I have installed by site):

mkdir ~/backup
sudo cp -r /var/www/ghost/* ~/backup

Images will be preserved in content/images stored by the year that they were published in. Any changes made to themes will also be preserved here. This can be used to debug problems after upgrading.

Snapshot

On Digital Ocean, stop the server. Then create a snapshot (can take a while). Finally turn the server back on.

Upgrade process

Connect to the server and upgrade the distribution with the following commands, accepting all changes.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade
sudo reboot

The reboot step might not be necessary but no harm in doing it. The above command also suggested to run sudo apt autoremove to remove unnecessary files. This command was a little slow to run, but probably a good practice.

The next step is to upgrade the Ghost command line interface (CLI) to the latest version. This needs to be done before any attempt to upgrade the application.

sudo npm i -g ghost-cli

As this was a major jump in my case, when I tried to run the actual upgrade command, it complained that I was using the incorrect version of NodeJS. Even running ghost status gave this error:

/usr/lib/node_modules/ghost-cli/lib/command.js:108
    static async _run(commandName, argv = {}, extensions) {

Before you can install the latest version of NodeJS, a new repository needs to be attached. Then apt-get will be able to install the latest version.

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash
sudo apt-get install -y nodejs

The final step is to run the upgrade process from the CLI as follows. Note that you should not run as sudo, although the installer will request for elevated privileges during the installation process. From the blogs installation folder, usually /var/www/<blog name>, run:

ghost update

Any problems with your chosen theme will be highlighted and you will be asked for confirmation. Note that Ghost needs to be restarted during this process.

Themes

If you have made any modifications to any theme files, for example, to add a comment section, it is unlikely that these changes will appear on the upgraded version. Compare the files taken in the backup to those in content/themes/<your theme name>. The files to concentrate on are the *.hbs files.

This site does not include comments, but another similar Blog that I manage does. When I ran through this process the changes to include comments was not upgraded. It was easy to identify the files that needed to be changed and copy the required bit across.

By default the Ghost upgrade process will back up the old versions of the site. These are stored in the versions folder within the installation. Check the timestamp of the files in that folder using ls -la and the file that was changed should stand out with a different timestamp.

If you had backed up the .hbs file, it should be easy to run a diff between the files to pick out what changes need to be copied across. Sometimes an upgrade will break the code required. If necessary, revisit the provider website for updated code.

You will need to restart Ghost for any changes to be picked up. Run the following from the installation folder and test some of the pages to ensure that everything looks correct and that there are no major unwanted differences from the previous site.

ghost update