Mental Pivot

Notes and observations from a lifelong pursuit of learning.

 
Insights and interesting reads delivered straight to your inbox.
Sign up for the free Mental Pivot Newsletter.

Upgrading from Ghost 3.x to 4.x on Digital Ocean

The popular Ghost blogging platform launched version 4.0 last week. This major release transforms Ghost into a powerful tool for memberships, subscriptions, and newsletters. You can read about the changes on the official Ghost site.

I run a self-managed installation of Ghost, so this means it’s time to upgrade. Unfortunately, it’s not as easy as clicking a magic button to update a Ghost instance—I wish it was!

That said, it’s not difficult to update Ghost if you take care when doing so, but it is easy to forget a key step and create unnecessary headaches for yourself. In the interest of helping others who might be upgrading their Ghost instance, I’m sharing my notes for moving Ghost 3.x to Ghost 4.x, the latest version of Ghost.

What follows are the basic steps I took to upgrade from Ghost 3.x to 4.x.

Note that I am running Ghost on a Digital Ocean droplet. I’ve covered the absolute basics in a prior post on the topic of upgrading from. Refer to these earlier posts if you need help navigating the command line to access your Digital Ocean instance:

Step 1: Check for Release Red Flags

It’s a good habit to check the Ghost forums and the Ghost GitHub repository for any big issues following the initial release.

If you see any unresolved issues plaguing multiple users, this is a good opportunity to consider pausing and waiting for a resolution or patch release (especially if there’s a significant unresolved bug).

Step 2: Backup Your Ghost Site

The backup process requires three steps.

  • Export contents/settings JSON:
    – Ghost 3.x: Click on the “Labs” link in the Ghost Dashboard and look for the JSON export button.– Ghost 4.x: Click on the “Settings” icon (the gear icon), then click on the “Labs” link and look for the JSON export button.
  • Download a copy of your theme (if necessary). You can find the active theme via the Ghost Dashboard.
  • Download your media/image folders.
    – These are not accessible via the Ghost Dashboard.– On my Digital Ocean instance, these files can be found in /var/www/ghost/content/images/– I use an SFTP client to login and download the contents of the images directory. You could also use SCP from the terminal or make a copy of the directory in another location on your server.

Step 3: Check and Update the Ghost CLI

The Ghost CLI (Command Line Interface) is the tool for managing and maintaining your Ghost installation. To ensure smooth upgrades, I check to make sure I’m running the latest version (link to the official Ghost CLI documentation).

The Ghost CLI can be updated using the following command:

sudo npm install -g ghost-cli@latest

Step 4: Update to the latest 3.x version

Before making the move from 3.x to 4.x, make sure you are running the latest 3.x release. For instance, I was running 3.31.5 and the latest release of 3.x (at the time) was 3.42.3.

You can always check on the latest official Ghost releases on GitHub.

To check your Ghost version:

ghost version

To update to the latest version of 3.x you can type:

ghost version 3.42.3

It’s a good idea to install and then check your site before proceeding.

Step 5: Update Node

Ghost uses the server-side JavaScript engine Node, so you will want to make sure that the version of Node you are using is still compatible with the latest version of Ghost CMS.

Ghost.org maintains a compatibility list on their site. Per their latest recommendation, these are the compatible versions:

  • Node 10.x = supported
  • Node 12.x = supported
  • Node 14.x = supported and recommended

You can check our version of Node with this command:

node -v

To download Node 14.x:

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -

To install Node 14.x:

sudo apt-get install -y nodejs

Step 6: Force Reinstall Current Ghost Version

This is an important step. It will reinstall any Node-specific dependencies.

ghost update 3.42.3 --force

If you are force reinstalling a different version of Ghost, just change the version number in the command.

Once finished, check your website and make sure everything is running as expected.

Step 7: Update to Ghost 4.x

This is the moment you’ve been waiting for. To update to the latest version of Ghost:

ghost update

Step 8: Update Your Theme

During the Ghost 4.x update, you might see some warnings about your Ghost theme’s compatibility with Ghost 4.x.

You can preemptively address those issues by using the web utility Gscan which lets you upload a theme and run a compatibility report.

In my case, there were some missing CSS classes I needed to add (e.g., the kg-bookmark class) and change a helper name in a theme partial. I just fixed the template, ran the updated version through Gscan, and then uploaded the theme via the Ghost Dashboard.

Final Thoughts

Recording the steps to the Ghost upgrade process is a good way to remind myself of some best practices and as a helpful guide to my future self. It’s easy to forget one critical step and then have to deal with a host of avoidable headaches. Having a reference document helps.

If you do run into any problems, the Ghost Documentation and Ghost Forum usually gets me pointed in the right direction.

Note that even with this latest upgrade, I neglected one critical step: I failed to check Ghost’s GitHub issues tracker. Had I done so, I would have seen that Ghost 4.1 introduced a performance bug that significantly slowed the response time when rendering a page. Had I seen that bug sooner, I would have waited for 4.1.1.

Fortunately, while writing this article, I noticed that the Ghost team pushed a 4.1.1 update that fixes this error. As soon as I publish this post, I’ll be off to install the update.



Get weekly email updates and additional content: Sign up for the free Mental Pivot Newsletter.