Ghost 1.0 was released in July 2017 marking the 100th release of Ghost, and the first major upgrade since the platform launched.

This is a major upgrade, with breaking changes and no automatic migration path. All publications upgrading from Ghost LTS versions (0.x) must be upgraded to Ghost 1.0 before they can be successfully upgraded to Ghost 2.0 and beyond.

This guide is useful for self-hosted Ghost users. If you are using Ghost(Pro) and require a manual upgrade, contact support!

Why upgrade to 1.0?

If you’re still running an older version of Ghost, we highly recommended that you upgrade to ensure you have all of the latest features, security and support. Ghost 0.x is no longer supported, which means it is not secure and more difficult to maintain. Here’s the current version history and end of life support.


Prerequisites

To upgrade to Ghost 1.0 you must be running an LTS version of Ghost (0.x). This upgrade requires creating a brand new install and importing your JSON content export, so it is a prerequisite to ensure you have a full backup in place before you begin. Here's a breakdown of the steps that you’ll go through:

  • Prepare your theme
  • Backup your content
  • Create a new Ghost v1.0.0 install
  • Import your JSON file
  • Copy your images to your new site
  • Upload your theme
  • Update external sites using Public API

Prepare your theme

Since there are breaking changes in the theme API between Ghost LTS and 1.0, your theme may need to be updated.

Check theme compatibility using gscan

Using the tool gscan is the fastest way to check your theme compatibility against all current versions of Ghost. It allows you to upload a zip file of your current theme to check for errors, deprecations and other compatibility issues.

  1. Download your current active theme as a .zip from the design settings page in Ghost admin.
  2. Upload this file on the gscan page
  3. Select 1.0.0 as the Ghost version to check your theme for this upgrade - it's also recommended you do this for the latest version of Ghost so that you are able to upgrade to that once this upgrade has been completed

The tool lists all errors and provide a full explanation and description of how to update your theme. All items listed as “must fix” are required to be updated within your theme for the 1.0.0 upgrade. Any items listed as “consider fixing” are recommended to ensure future upgrades are smoother.


Backup your content

When backing up a Ghost site, there are 2 main things that need to be done:

  1. Download a JSON export from Ghost admin
  2. Ensure you have a backup of your content folder

JSON export

Retrieve an up-to-date JSON export from the Ghost admin in the labs section, which can be accessed at yourdomain.com/ghost/settings/labs/. This downloads a JSON export file that you’ll need later to your machine.

Content folder backup

All user-provided data such as images and themes exist in the /content/ folder. We strongly recommend making a copy of these files. To do this run the following command on yours sever:

cp -r content /tmp/content-backup

Create a new Ghost 1.0.0 install

Since there is no automatic upgrade path for this version of Ghost, you'll need to create a clean install of Ghost 1.0.0 to production.

Follow the step-by-step guide to install Ghost on your server using the Ghost CLI. When you install Ghost, use the installation command with the version number to install the correct version of Ghost for this upgrade:

ghost install --v1

Upon install, follow the setup questions as directed in the guide and ensure your new install is configured correctly.


Import your JSON file

Once Ghost has been reinstalled on your server, you can import your content using the JSON file that you exported earlier. Import your file in the labs screen under settings in Ghost admin.

All user accounts are locked on import

The Ghost importer does not import user passwords or tokens. All user accounts (except the one used to do the import) are locked on import. Use the password reset mechanism to regain access.


Copy your images

Your content folder backup that you created earlier now needs to be moved from your existing directory <old-ghost-dir>/content/images to the new blog directory <new-ghost-dir>/content/images.

This content directory functions the same, and exists in the same place as in previous Ghost versions. After copying your files into the new /content/ folder, make sure they belong to the correct Ghost user by running:

sudo chown -R ghost:ghost content

Upload your theme

Once your theme is fully prepared for Ghost 1.0.0 following the guidelines given on gscan.ghost.org, upload the final .zip file into your new Ghost install. Themes are uploaded in the design settings page inside of your Ghost admin.

To upload a theme manually, copy the theme into <new-ghost-dir>/content/themes. Ensure the folder is owned by the ghost user and run ghost restart to make Ghost see it.


Update external sites using Content API

If you have external sites which are using the Content API to pull data from Ghost, you'll need to make some updates to ensure this stays working. Consult the API documentation for further information.


Summary

Now that you have successfully upgraded from Ghost LTS to Ghost 1.0, you can use ghost-cli to upgrade to the latest version of Ghost with all of the latest features 🎉

The 2.0.0 upgrade is considerably less manual than this one, and it's highly recommended you do this now.