Upgrade to Node v18 for Ghost CMS & common errors

Starting with version 5.71.0 Ghost has dropped support for Node 16. This means for newer Ghost CMS version you need to upgrade your Node version to 18. The current recommended Node version is Node v18 Hydrogen LTS.

It's a good idea to keep up-to-date with the recommended Node version for Ghost, because that version is used in production on Ghost(Pro) which means it's heavily tested and issues are actively fixed by the Ghost core team.

How to upgrade Node.js

Node has changed their distribution method, which means there are some configuration adjustments necessary in order to upgrade.

Follow the steps below to upgrade:

1. Download and import the Nodesource GPG key

# Update local package index
sudo apt-get update
# Install necessary packages for downloading and verifying new repository information
sudo apt-get install -y ca-certificates curl gnupg
# Create a directory for the new repository's keyring, if it doesn't exist
sudo mkdir -p /etc/apt/keyrings
# Download the new repository's GPG key and save it in the keyring directory
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

2. Create deb repository

# Define the desired Node.js major version
NODE_MAJOR=18
# Add the new repository's source list with its GPG key for package verification
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_${NODE_MAJOR}.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

3. Install/upgrade Node.js:

# Update local package index to recognize the new repository
sudo apt-get update
# Install Node.js from the new repository
sudo apt-get install -y nodejs

Update your Ghost version

Ghost doesn't recommend updating Node and Ghost at the same time. Reinstalling the current version of Ghost ensures that Node is updated correctly first, and that should make the Ghost updated process smooth.

1. Find out your current Ghost version:

ghost version

2. To reinstall the current version of Ghost:

ghost update {your_version} --force

The --force addition makes sure to trigger a re-install of dependencies.

Error "connect ECONNREFUSED ::1:3306"

After the the NodeJS upgrade and trying to run ghost update, even though the update process was successful, I got the following error:

Message: Ghost was able to start, but errored during boot with: connect ECONNREFUSED ::1:3306
Help: Unknown database error

Turns out this is because Node v18 prefers ipv6 resolution over ipv4. Depending on your MySQL configuration if it isn't listening on the ipv6 interface then node won't be able to connect to it.

There is a quick fix for this, by changing your database host from localhost to 127.0.0.1 in your Ghost config.

To do this:

1. Open your config.production.js file

  "database": {
    "client": "mysql",
    "connection": {
      "host": "localhost",
      "user": "your_user",
      "password": "your_pw",
      "database": "your_db"
    }
  },

2. In the database section, change the host property, then save the file

"host": "127.0.0.1"

3. Restart ghost

ghost restart

Your ghost instance should be starting now.