Ghost 1.0.0 is a major upgrade, with breaking changes and no automatic migration path. Although this migration is going to be more painful than usual, we hope you'll find it's worth it! If you install using Ghost CLI then from 1.0.0 onwards, upgrades are going to be as simple as
ghost update 🎉
To migrate to 1.0.0 you will need to handle breaking changes in the Theme API, and in the Public API if you make use of it.
Unlike previous upgrades you will be creating a brand new install and importing your JSON export, instead of migrating the old one. As with previous upgrades, we very strongly recommend backing up before you begin.
Only really this time. Please back up. Please.
Here's a basic breakdown of the migration steps:
- Prepare your theme in advance
- Backup your content using the JSON exporter
- Create a brand new Ghost v1.0.0 site following our install guide
- Use Ghost v1.0.0 Importer to import existing content
- Copy your images to your new site.
- Upload your theme - your theme will not be uploaded from the importer
- Update external sites using Public API - if you fetch data via the Public API, you'll need to update the credentials on your external sites
Public API breaking changes
There are 2 issues which impact the Public API when accessed from external sites:
- Ghost 0.11.x LTS exports do not include clients & trusted domains and therefore will not be imported to your new site.
/shared/ghost-url.min.jsutil has been moved and renamed to
Read the API migration guide for more details of how to fix this.
Markdown breaking changes
Automatic footnote numbering is no longer supported in 1.0. If you have
[^n] style footnotes in any of your posts you will need to manually update them to be fully identified with a number
[^1] or a label
Please see our Markdown Guide for further information on supported footnote syntax.
There are breaking changes in the theme API between Ghost LTS and 1.0.0, that mean your theme may need to be updated before you are able to update.
The best way to check this is with gscan. If you navigate to
yourdomain.com/ghost/settings/ and download your current active theme, you can then upload it to https://gscan.ghost.org to get a report on any changes that need to be made.
There's a full guide to migrating themes over in the theme docs.
Copying your SQLite3 DB will not work!
When migrating to Ghost 1.0, you will need a JSON export file. There is no way to migrate to 1.0.0 using only an SQLite3 DB file.
For general backups, it is possible to keep a copy of your sqlite database file although you should always stop Ghost before copying the file to prevent file corruption.
When backing up a Ghost site, there are 2 main things that need to be done. 1. grab an export from labs, and 2. ensure you have a backup of your content folder.
To get an export, in your existing Ghost site, navigate to
yourdomain.com/ghost/settings/labs/ (the settings > labs page in Ghost-Admin) and click on the Export button. It should look something like this:
lts labs page
This will download your JSON export file that you need later.
All user-provided data, such as images and themes, live in the
/content/ folder. It's always a good idea to make a quick copy of these files so you've got access. Easiest way to do this is to run
cp -r content /tmp/content-backup on your server.
You can also download your active theme from the labs page.
Next you'll need a clean install of Ghost 1.0.0.
Check out our install guide to create a new production site using Ghost CLI.
All user accounts are locked on import
As has always been the case, 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. Users will need to use the password reset mechanism to regain access.
On your new site import navigate to
yourblogdomain.com/ghost/#/settings/labs (the settings>labs page in Ghost-Admin)
Click Choose file and select the JSON export file created in [step 1] then click on the Import button.
v1.0.0 Labs page
The importer will not import themes from LTS blogs
You should see a warning that your theme has not been imported, this is expected and you can continue on to step 4.
If see other warnings or errors, you may need to troubleshoot your Ghost Import.
Your content directory functions the same, and exists in the same place in 1.0 as in previous Ghost versions.
You need to copy/move your images from your existing directory
<old-ghost-dir>/content/images to the new blog directory
After copying any files into the
/content/ folder, you must make sure they belong to the Ghost user. This can be done by running
sudo chown -R ghost:ghost content inside of your Ghost install.
yourblogdomain.com/ghost/#/settings/design (the Settings>Design page in Ghost Admin) then click
Upload a Theme button and follow on-screen instructions.
Upload a theme
You can also copy the theme into
<new-ghost-dir>/content/themes, but you must make sure the folder is owned by the ghost user and will need to run
ghost restart to get Ghost to see it.
Posts per page setting:
The posts per page setting is now controlled by your theme, and this will default to 5 posts if not set.
Ghost now uses the "Publication Icon" in settings to output a favicon automatically. Please upload a 60px by 60px icon in
/settings/general/ - this will be used to output an icon, including a favicon.ico, anywhere that icons are needed.
If you have external sites which are using the Public API to pull data from Ghost, you'll need to make some updates to ensure this stays working.
See the API migration guide for more information.