Ghost 1.0 was released in July 2017 marking the 100th release of Ghost, and the first major upgrade since the platform launched. This update includes a new editor, an updated UI, night shift mode and lots more new features.

Ghost 1.0.0 is a major upgrade, with breaking changes and no automatic migration path. To migrate to 1.0.0 you’ll need to handle breaking changes in the Theme API, and in the Public API if you make use of it.

This guide is useful for all self-hosted Ghost users. If you are using Ghost(Pro) then you are automatically upgraded to the latest version of Ghost.

Why upgrade to 1.0?

Since Ghost 1.0 has breaking changes with no automatic migration path, all publications running Ghost LTS versions (0.x) must be upgraded to Ghost 1.0 before they can be successfully upgraded to Ghost 2.0 and beyond.

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. Here’s the current version history and end of life support.

To upgrade from Ghost 1.x to Ghost 2.x using the ghost-cli use the Migrating to 2.0 guide.

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 migration 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 migration

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 migration. 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 migration:

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 Public 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.


Troubleshooting

If you run into any issues or errors when upgrading to Ghost 2.0, use the search function on this site to find solutions for common issues, or head to the community forum.


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.