Upgrading Ghost — Safe Upgrade Procedures, Testing and Rollback

In this tutorial, you'll learn how to safely upgrade Ghost CMS — reading release notes for breaking changes, using Ghost CLI upgrade commands, testing upgrades in a staging environment, rolling back failed upgrades, and automating the process for minimal downtime.

What You'll Learn

• The Ghost versioning scheme and release cycle
• Reading release notes for breaking changes
• Pre-upgrade checklist and prerequisites
• Using ghost upgrade CLI command
• Testing upgrades in a staging environment
• Rolling back to a previous version
• Database migration during upgrades
• Theme compatibility checking
• Custom integration testing after upgrades
• Automating upgrades with CI/CD

Why It Matters

Ghost releases updates regularly with new features, security patches, and bug fixes. Staying on an outdated version means missing critical security updates and performance improvements. But upgrading without preparation can break your site — themes may be incompatible, custom integrations may fail, or database migrations may introduce errors. A structured upgrade process ensures you get the benefits without the downtime.

Real-World Use

A Ghost site running version 4.x plans to upgrade to 5.x. The release notes mention several breaking changes: the members API has new endpoints, the Handlebars helpers have changed for content visibility, and the theme structure requires updates. The team creates a staging copy of their site, upgrades there first, tests all integrations, fixes theme compatibility issues, and schedules the production upgrade during low traffic. The production upgrade takes 3 minutes and works without issues.

Learning Path

flowchart LR
  A["Database Management"] --> B["Upgrading Ghost
You are here"]:::current
  B --> C["Security"]
  C --> D["Monitoring & Logging"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Ghost Versioning

Ghost follows semantic versioning: MAJOR.MINOR.PATCH.

Pre-Upgrade Checklist

Before any upgrade, complete this checklist:

1. Read Release Notes

# Check current version
ghost version

# View changelog online
# https://github.com/TryGhost/Ghost/releases

Pay attention to:

• Breaking changes (highlighted in bold or warning sections)
• Deprecated features that will be removed
• Database migration notes
• Theme compatibility requirements
• Custom integration changes

2. Verify System Requirements

# Check Node.js version
node --version

# Check MySQL version
mysql --version

# Check available disk space
df -h

Ghost 5.x requires Node.js 18.x LTS. Verify your server meets the new version's requirements.

3. Create a Full Backup

# Backup the database
# For MySQL:
mysqldump --user=ghost_user --password ghost_production \
  --single-transaction --routines --triggers \
  | gzip > pre_upgrade_$(date +%Y%m%d).sql.gz

# Backup the entire Ghost directory
tar -czf ghost_backup_$(date +%Y%m%d).tar.gz \
  /var/www/ghost/content/ \
  /var/www/ghost/current/ \
  /var/www/ghost/versions/

4. Verify Current Stability

Ensure your current Ghost instance is running without errors:

ghost status
ghost log errors --tail 20

Using Ghost CLI Upgrade

Standard Upgrade

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

# Check what version is available
ghost upgrade --check

# Perform the upgrade
ghost upgrade

The CLI performs these steps:

1. Downloads the new version to versions/
2. Installs npm dependencies for the new version
3. Runs database migrations
4. Stops the current Ghost process
5. Symlinks current/ to the new version
6. Restarts Ghost

Upgrade to a Specific Version

# Upgrade to a specific minor/patch version
ghost upgrade v5.15.0

# Upgrade from 4.x to 5.x (major upgrade)
ghost upgrade v5.0.0

Dry Run

Check what the upgrade will do without performing it:

ghost upgrade --dry-run

Database Migrations

During major upgrades, Ghost runs database migrations. These are automatic but need monitoring.

How Migrations Work

1. Ghost compares the current database schema to the new version's expected schema
2. New tables, columns, and indexes are created
3. Data is transformed if the schema changed (e.g., new member fields)
4. The migration is logged in the database with a version number

Monitoring Migrations

# Watch migration progress
ghost log

# Check migration status after upgrade
ghost db info

Migration Failures

If a migration fails:

1. Ghost does not start
2. The error appears in content/logs/
3. The database remains in its pre-migration state (migrations are transactional)
4. You can roll back and fix the issue

Common migration failures:

Testing in Staging

Never upgrade production without testing first.

Setting Up a Staging Environment

# Copy production database to staging
mysqldump --user=ghost_user --password ghost_production \
  | mysql --user=ghost_staging --password ghost_staging

# Copy content (images, themes)
rsync -av /var/www/ghost/content/ /var/www/staging/content/

# Set up staging Ghost instance
ghost install --url https://staging.yoursite.com --db mysql

Testing Checklist

After upgrading the staging instance:

• Homepage loads correctly
• All posts and pages render without errors
• Tags and authors display properly
• Members can sign up and log in
• Newsletter subscription works
• Theme renders all templates correctly
• Custom integrations return expected data
• Admin panel functions (create post, upload image, edit settings)
• Webhooks fire correctly
• API endpoints return expected responses
• Mobile responsive layout is correct
• Page speed is acceptable

Rolling Back

If a production upgrade fails, roll back immediately.

Rollback Steps

# 1. Stop Ghost
ghost stop

# 2. Restore the previous version
# Ghost keeps the old version in versions/
cd /var/www/ghost
rm current
ln -s versions/<previous-version> current

# 3. Restore the database
# For MySQL:
gunzip < pre_upgrade_$(date +%Y%m%d).sql.gz \
  | mysql --user=ghost_user --password ghost_production

# 4. Start Ghost with the old version
ghost start

# 5. Verify the site is working
ghost log --tail 5

When to Roll Back

Roll back immediately if:

• The admin panel does not load
• A database migration failed
• The public site returns 502 or 500 errors
• Members cannot log in or subscribe
• Critical custom integration is broken

Theme Compatibility

Checking Theme Compatibility

# Enable debug mode to see template errors
ghost config --development

In the admin panel, check Settings → Theme for compatibility warnings.

Common Theme Issues After Upgrade

Custom Integration Testing

After upgrading, test all custom integrations:

1. Webhooks: Trigger each Webhook and verify the payload
2. API clients: Run API tests against the staging instance
3. Zapier/Make/IFTTT: Verify connections are active
4. Custom storage adapters: Upload and retrieve files
5. SSO providers: Test authentication flow

Automating Upgrades

For multiple Ghost sites, automate the upgrade process:

#!/bin/bash
# upgrade-ghost.sh

SITE_DIR="/var/www/ghost"
BACKUP_DIR="/home/ghost/backups"
SITE_URL="https://yoursite.com"

# 1. Backup
echo "Creating backup..."
mysqldump --user=ghost_user --password ghost_production \
  | gzip > $BACKUP_DIR/pre_upgrade.sql.gz
tar -czf $BACKUP_DIR/pre_upgrade_content.tar.gz $SITE_DIR/content/

# 2. Test connectivity
echo "Testing current site..."
curl -sf -o /dev/null $SITE_URL || exit 1

# 3. Run upgrade
echo "Running upgrade..."
cd $SITE_DIR
ghost upgrade || {
  echo "Upgrade failed, rolling back..."
  # Rollback logic here
  exit 1
}

# 4. Verify upgrade
echo "Verifying upgrade..."
sleep 10
curl -sf -o /dev/null $SITE_URL && echo "Upgrade successful"

Common Mistakes

1. Upgrading without a backup: If an upgrade fails, the database may be partially migrated and unrecoverable. Always take a full database and content backup before any upgrade, especially major version upgrades.

2. Skipping release notes: Major versions often include breaking changes — removed APIs, deprecated helpers, new system requirements. Reading release notes first prevents surprise failures.

3. Upgrading production without staging first: Upgrading production directly is the most common cause of Ghost site outages. Always upgrade a staging copy first, run the full testing checklist, then upgrade production.

4. Not checking theme compatibility: A theme that worked in Ghost 4.x may use helpers or templates that were removed in 5.x. The site may render blank pages. Check theme compatibility in staging before upgrading production.

5. Assuming rollback is simple: Rolling back the Ghost binary is straightforward, but rolling back the database can be complex if new data was created after the upgrade. If you upgrade and then operate the site for a day before rolling back, the database pre-backup is outdated and you lose the day's data.

6. Upgrading during peak traffic: Upgrades require stopping and restarting Ghost, causing brief downtime. Performing upgrades during peak hours affects user experience. Schedule upgrades during low-traffic Windows (e.g., 3 AM on a weekday).

Practice Questions

1. What is the difference between major, minor, and patch upgrades in Ghost? Answer: Major upgrades (e.g., 4.x to 5.x) introduce breaking changes and require database migrations. Minor upgrades (e.g., 5.0 to 5.1) add features without breaking changes. Patch upgrades (e.g., 5.0.0 to 5.0.1) include bug fixes and security patches with minimal risk.

2. What steps should you take before a major Ghost upgrade? Answer: Read the release notes for breaking changes, verify system requirements (Node.js version, MySQL version, disk space), create a full database and content backup, ensure the current site is stable, set up a staging environment, and test the complete upgrade process there first.

3. How do you roll back a failed Ghost upgrade? Answer: Stop Ghost, symlink current/ to the previous version in versions/, restore the pre-upgrade database backup, restart Ghost, and verify the site is working. Act quickly before new data accumulates that would make database rollback impossible.

4. Challenge: Create a complete upgrade automation script for Ghost. The script should: check release notes for the latest version, create a full backup, perform the upgrade, run a health check (HTTP 200, admin panel access, test API call), and implement automatic rollback if the health check fails.

FAQ

Mini Project

Your task: Create a complete Ghost upgrade playbook.

1. Set up a staging environment that mirrors production (database, content, themes).
2. Perform a staged upgrade from your current Ghost version to the latest available version.
3. Document every breaking change encountered and how you fixed it.
4. Create a rollback procedure document with step-by-step commands.
5. Write an automated upgrade script with health checks and automatic rollback.
6. Test the full upgrade workflow three times: staging test, production dry-run, production execution.
7. Document the expected downtime and communication plan for stakeholders.

This exercise gives you a repeatable, safe upgrade process for any Ghost site.

What's Next

Now that upgrade procedures are in place, learn about security:

Continue to Lesson 38: Security — Hardening Ghost, SSL, firewalls, and protection.

Related lessons:

• Monitoring & Logging — Track and diagnose issues
• Production Deployment — Deploy Ghost for scale