How to Upgrade Ghost Installation

This guide walks you through upgrading a self-hosted Ghost installation on a VPS or server. Whether you're running on Ubuntu, Debian, or another Linux distribution, these steps will help you safely update Ghost to the latest version while avoiding common pitfalls.

Prerequisites

Before you begin, ensure you have:

• SSH access to your server
• sudo privileges for your user account
• At least 1GB of RAM available (the most common cause of update failures is running out of memory)
• A recent backup of your Ghost installation

Step 1: Check Your Current Setup

First, SSH into your server and check your current versions:

# Check Ghost version and installation location
ghost ls

# Check current Node.js version
node -v

# Check Ghost-CLI version
ghost -v

# Check npm version
npm -v

Important: Take note of these versions. You'll need them if something goes wrong.

Step 2: Create a Backup

Never skip this step. Create a full backup before any upgrade:

cd /var/www/ghost  # or your Ghost installation directory
ghost backup

This creates a zip file containing:

• Content (JSON export)
• Member data (CSV)
• Themes
• Media files
• Configuration files

Pro tip: Download the backup to your local machine:

# From your local machine
scp user@your-server-ip:/var/www/ghost/backup-*.zip ~/Desktop/

Step 3: Check Node.js Version Requirements

Ghost has strict Node.js version requirements. As of Ghost 6.x:

Check the official Node.js requirements for the most current information.

Step 4: Update Node.js (If Required)

If your Node.js version is outdated, update it first:

# Check current version
node -v

# Install Node.js 22.x (for Ghost 6.x)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify new version
node -v

Alternative using nvm (Node Version Manager):

# Install specific version
nvm install 22

# Use it
nvm use 22

# Set as default
nvm alias default 22

Step 5: Update Ghost-CLI

Always update Ghost-CLI before updating Ghost itself:

sudo npm install -g ghost-cli@latest

# Verify version (should be 1.28.2 or higher for Ghost 6.x)
ghost -v

If you encounter permission errors:

# Clear npm cache and reinstall
sudo npm cache clean --force
sudo npm install -g ghost-cli@latest

Step 6: Update npm (Optional but Recommended)

sudo npm install -g npm@latest
npm -v

Step 7: Switch to the Correct User

Ghost should be managed by the user who originally installed it:

# If installed as a specific user (e.g., 'ghost' or your username)
sudo -i -u ghost

# Or switch to your user
sudo -i -u yourusername

Step 8: Navigate to Ghost Directory

cd /var/www/ghost  # Default location, yours may differ

Step 9: Update to Latest Minor Version First

If you're upgrading across major versions (e.g., 4.x to 5.x to 6.x), you must first update to the latest minor version of your current major release:

# If on Ghost 4.x, update to latest 4.x first
ghost update v4

# If on Ghost 5.x, update to latest 5.x first
ghost update v5

Step 10: Perform the Update

Now run the actual update:

ghost update

Ghost-CLI will:

1. Download the latest version
2. Check compatibility
3. Run database migrations
4. Restart Ghost

Troubleshooting Common Issues

Error: Node Version Mismatch

Ghost v6.x.x is not compatible with the current Node version.
Your node version is X.X.X, but Ghost vX.X.X requires ^22.0.0

Solution: Update Node.js as shown in Step 4.

Error: Ghost-CLI Version Too Old

Ghost v6.x.x is not compatible with this version of the CLI.

Solution: Update Ghost-CLI:

sudo npm install -g ghost-cli@latest

Error: Update Failed (Memory Issues)

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solution: Increase Node.js memory limit:

NODE_OPTIONS="--max-old-space-size=1024" ghost update

Or temporarily add swap space:

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Run update, then remove swap if desired

Error: MySQL Connection Issues with Node 18+

Node.js 18+ prefers IPv6, which can cause MySQL connection failures.

Solution: Edit your Ghost config to use 127.0.0.1 instead of localhost:

ghost config set database.connection.host 127.0.0.1

Error: Binary Dependencies Need Recompilation

After updating Node.js, Ghost's binary dependencies may need recompilation.

Solution: Force reinstall:

ghost update --force

Error: Permission Denied

The path /home/user/ is not readable by other users

Solution: Fix permissions:

sudo chown -R ghost:ghost /var/www/ghost
sudo chmod 775 /var/www/ghost

Site Shows 503 Error After Update

Solution: Check logs and try restarting:

# Check what's happening
ghost log

# Try restarting
ghost restart

# If that fails, run directly to see errors
ghost run

Rolling Back

If the update fails catastrophically, you can roll back:

ghost update --rollback

Or restore from your backup manually.

Post-Update Verification

After a successful update, verify everything works:

# Check Ghost is running
ghost status

# Check the version
ghost version

# View recent logs
ghost log

# Visit your site in a browser
# Check the admin panel at https://yoursite.com/ghost/

Best Practices

1. Always backup first - This cannot be stressed enough
2. Update during low-traffic hours - Minimize impact on readers
3. Test in staging first - If possible, test updates on a staging server
4. Read the changelog - Check Ghost's changelog for breaking changes
5. Keep Ghost-CLI updated - Many issues stem from outdated CLI versions
6. Monitor after updates - Watch logs for the first few hours after updating

Quick Reference: Common Commands

# Check status
ghost ls
ghost status

# Start/Stop/Restart
ghost start
ghost stop
ghost restart

# View logs
ghost log
ghost log -f  # Follow logs in real-time

# Backup
ghost backup

# Update
ghost update
ghost update --force  # Force reinstall
ghost update --rollback  # Undo last update

# Diagnostics
ghost doctor
ghost doctor startup

# Configuration
ghost config  # View all config
ghost config url  # View specific setting
ghost config set url https://example.com  # Change setting

References

• Ghost Official Update Guide
• Ghost Node.js Version Requirements
• Ghost CLI Documentation
• Ghost Changelog
• NodeSource Node.js Distributions