Upgrading Ghost CMS from version 5 to version 6 is a major version jump that requires careful planning and execution. Having just completed this upgrade on a production blog running Ghost v5.78.0 on Ubuntu 20.04 with Node.js v18.19.0, I'm sharing this comprehensive guide to help others navigate the process smoothly.

Ghost v6 introduces significant improvements including ActivityPub support for federated publishing, enhanced performance, and better content management features. However, the upgrade path has specific requirements that must be met in sequence to avoid breaking your production site.

Critical Requirements

Before starting, understand these non-negotiable requirements for Ghost v6:

  • MySQL 8.0 (MySQL 5.x is NOT supported)
  • Node.js v22.13.1 or higher (But Ghost v5 requires Node 18.x)
  • Latest Ghost v5 version before upgrading to v6
  • Updated Ghost-CLI for smooth migration
  • Ubuntu 20.04 or newer (tested on 20.04 LTS)

Pre-Upgrade Warnings

⚠️ Common Pitfalls to Avoid

  1. Node.js Version Mismatch: Ghost v5 doesn't support Node 22, and Ghost v6 doesn't support Node 18. You'll need to manage Node versions carefully during the upgrade.
  2. MySQL Version: Ghost v6 will NOT work with MySQL 5.x. Check your version first - this is the most common upgrade blocker.
  3. Ghost-CLI Issues: The CLI tool may have directory permission issues during updates. Be prepared to manually clean up node_modules.
  4. Database Connection: Node.js v18+ prefers IPv6, which can cause MySQL connection issues. You'll need to update your configuration.
  5. Theme Compatibility: Your theme may show warnings or errors after upgrading. While usually non-critical, review these carefully.

Step-by-Step Upgrade Process

Step 1: Check Your Current Setup

bash

# Check current versions
cd /var/www/ghost
ghost version  # Current Ghost version
node -v        # Should be v18.x.x for Ghost v5
ghost-cli -v   # Current CLI version
mysql --version  # MUST be MySQL 8 for Ghost v6

If MySQL is version 5.x, upgrade it first before proceeding.

Step 2: Create Complete Backups

Never skip this step on a production site:

bash

# Navigate to Ghost directory
cd /var/www/ghost

# Create Ghost's built-in backup
ghost backup

# Export content to JSON
ghost export content-$(date +%Y%m%d-%H%M%S).json

# Create manual backup directory
mkdir -p ~/ghost-backup-$(date +%Y%m%d)

# Copy critical files
cp content-*.json ~/ghost-backup-$(date +%Y%m%d)/
cp -r content/images ~/ghost-backup-$(date +%Y%m%d)/
cp -r content/themes ~/ghost-backup-$(date +%Y%m%d)/
cp config.production.json ~/ghost-backup-$(date +%Y%m%d)/

Step 3: Update Ghost-CLI

If you encounter npm directory errors:

bash

# Check for problematic directories
ls -la /usr/lib/node_modules/ | grep ghost

# Clean up if necessary
sudo rm -rf /usr/lib/node_modules/ghost-cli
sudo rm -rf /usr/lib/node_modules/.ghost-cli*
sudo npm cache clean --force

# Install latest Ghost-CLI
sudo npm install -g ghost-cli@latest

# Verify installation
ghost -v

Step 4: Update to Latest Ghost v5

bash

cd /var/www/ghost
ghost update

This ensures you're on the latest v5 version (like 5.130.x) before the major upgrade.

Step 5: Update Database Configuration

This prevents IPv6 connection issues with newer Node versions:

bash

cd /var/www/ghost
nano config.production.json

Find the database section and change:

json

"database": {
  "client": "mysql",
  "connection": {
    "host": "127.0.0.1",  // Changed from "localhost"
    "user": "your_db_user",
    "password": "your_db_password",
    "database": "your_db_name"
  }
}

Step 6: The Node.js Dance - Critical Sequence

This is the trickiest part. Ghost v5 requires Node 18, but Ghost v6 requires Node 22:

bash

# First, ensure you're on Node 18 (for Ghost v5)
node -v  # Should show v18.x.x

# If not on Node 18, install it:
sudo apt-get remove -y nodejs
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Force reinstall current Ghost version
cd /var/www/ghost
ghost update --force

Step 7: Upgrade Node.js to v22

bash

# Remove Node 18
sudo apt-get remove -y nodejs

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

# Verify
node -v  # Should show v22.x.x

Step 8: Update to Ghost v6

bash

cd /var/www/ghost

# Stop Ghost before major upgrade
ghost stop

# Run the update
ghost update

# If it complains about Node version mismatch, force it:
ghost update --v6
# OR
ghost update 6.0.9 --force

Step 9: Start Ghost and Verify

bash

# Start Ghost
ghost start

# Check status
ghost status

# Review logs for any errors
ghost log

# Test your site
curl -I https://your-domain.com

Step 10: Update Nginx Configuration (if applicable)

Add ActivityPub support to your Nginx configuration:

bash

sudo nano /etc/nginx/sites-available/your-ghost-site

Add these blocks BEFORE your main location block:

nginx

location ~ /.ghost/activitypub/* {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $http_host;
    add_header X-Content-Type-Options "nosniff";
    proxy_ssl_server_name on;
    proxy_pass https://ap.ghost.org;
}

location ~ /.well-known/(webfinger|nodeinfo) {
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $http_host;
    add_header X-Content-Type-Options "nosniff";
    proxy_ssl_server_name on;
    proxy_pass https://ap.ghost.org;
}

Reload Nginx:

bash

sudo nginx -s reload

Handling Theme Compatibility Warnings

After upgrading, you may see theme warnings like:

  • "Not all page features are being used"
  • "Replace {{twitter_url}} with {{x_url}}"
  • "Using limit='all' in {{#get}} helper is not supported"

These warnings are typically non-critical. Your site will continue to function, but consider:

  1. Updating to a Ghost v6 compatible theme version
  2. Manually fixing deprecated syntax in theme files
  3. Testing with a default theme to isolate issues

Troubleshooting Common Issues

MySQL Connection Errors

If you see "connect ECONNREFUSED ::1:3306":

  • Ensure config.production.json uses "127.0.0.1" not "localhost"
  • Restart Ghost after configuration changes

Node Version Conflicts

If Ghost complains about Node version:

  • Ghost v5 needs Node 18.x
  • Ghost v6 needs Node 22.x
  • Use the version appropriate for your current Ghost version

Ghost Won't Start After Upgrade

bash

ghost doctor  # Run diagnostics
ghost log -f  # Check real-time logs
ghost restart # Try a full restart

Rollback Plan

If something goes catastrophically wrong:

bash

# Stop Ghost
ghost stop

# Restore from backup
ghost backup --restore

# Or manually restore
mysql -u your_user -p your_database < ~/ghost-backup-*/backup.sql
cp -r ~/ghost-backup-*/images/* content/images/
cp -r ~/ghost-backup-*/themes/* content/themes/

# Downgrade Node if needed
sudo apt-get remove -y nodejs
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Start Ghost
ghost start

Post-Upgrade Checklist

  • Ghost admin panel accessible
  • Posts and pages loading correctly
  • Images displaying properly
  • Theme rendering without errors
  • Email newsletters working (test send)
  • Member signup/login functioning
  • Database backups scheduled
  • Monitoring alerts configured

Conclusion

Upgrading Ghost from v5 to v6 requires careful attention to the Node.js version requirements and proper sequencing of updates. The key is understanding that you need Node 18 for Ghost v5, then Node 22 for Ghost v6, and managing this transition smoothly.

Remember: always backup first, check MySQL version compatibility, and be prepared to handle the Node.js version dance. With proper preparation and following these steps, your upgrade should complete successfully.

If you found this guide helpful, consider sharing it with others in the Ghost community who might be planning their own upgrades.

Share this post