Ghost 4: the Major Upgrade

Finally, our chronicles are on the latest version of the Ghost software. The preparation and tests have taken a while, yet the upgrade brought down the site for an hour. This small how-to could be helpful if you have a standalone Ghost platform and plan to upgrade it to the latest & greatest.

Node.js and NPM

For Ghost v3.x I have some Node v10 installed, but the new version prefers Node v12 or higher. If you share Node binaries with multiple projects, make sure that your new binaries will work with all applications.

The NPM package manager also should be updated. I have shared Node binaries, so run it as a root user and with global switch.

# npm install -g npm@latest

Your updated npm version would be 7.12.0 or higher.

Ghost Command Line Interface

With all the new Node binaries, it's time to upgrade Ghost CLI. Again, I have it as a global application:

# npm install -g ghost-cli@latest

As of today, the latest version of this package is 1.17.0. If you made it up to this point, you are ready for a site upgrade.


Take a pause and make sure that you have the latest site backup. Run through the checklist below and see if you:

  • Downloaded the site content
  • Downloaded your custom site theme
  • Have a backup of your content folder
  • Have a backup of your database

I have a tiny local VM to test all dangerous operations before I go to the production system. Additionally, I restore my site backups to validate them and keep local VM consistent.


Ghost upgrade

The engine upgrade is as simple as the previous steps. Before the main upgrade, make sure that you have a compatible version of Ghost 3 - 3.42.5. To do so, upgrade your current v3.x installation:

$ cd $GHOST_SITE/
$ ghost update v3

This command applies the latest changes and restarts the engine if your site was up. Check your site and admin console to see that you are still online.
Now it's time for the last jump, to the Ghost v4.4.0:

$ ghost update

Potential upgrade issues

If you keep your Ghost data in the MySQL database, you may run into some post-upgrade issues. An instrumental piece describes similar symptoms, but my final set of trials and runs was slightly different.

--- Added with no issues
alter table members_stripe_customers_subscriptions add column stripe_price_id varchar(255) not null default '' unique key ;

--- Failed for me. Key was already defined 
alter table members_stripe_customers_subscriptions add key (stripe_price_id);

--- Added the mssing table
create table members_products (
  id varchar(24) not null primary key, 
  member_id varchar(24) not null references members(id) on delete cascade,
  product_id varchar(24) not null references products(id) on delete cascade, 
  sort_order integer unsigned not null default 0);

After several database alterations and ghost starts, it finally came through, and you can read this post on the updated site.