Back in May the Ghost team released ghost 0.8.0. This is the first time I've had an opportunity to upgrade Ghost and I'm always hesitant to upgrade to new releases of anything (especially this blog) until they've had a good run in.
A prospective customer of the theme I'm using on this blog Angsty theme, asked if it was 0.8.0 compatible so I decided it was time to upgrade.
When upgrading a framework, you can never be too sure if a theme that you wrote for an earlier version will be forward compatible with future releases, however, I was surprised to find out after the upgrade there were no glitches. Also, the release process proved to be fairly straightforward - good work Team Ghost!
In addition, I have my own release process for sending files up to my AWS servers everytime I make changes to the site (including Ghost upgrades), as detailed in my How to drive your Ghost Blog using Continuous Delivery series.
I was pretty worried this wouldn't work.
Thankfully everything is still working a-okay.
So on to how I upgraded it. I mainly followed Ghost.org instructions on How to Upgrade Ghost
Prepare your blog
Before you upgrade there's always a few points of due diligence you have to take into account prior to upgrading. To upgrade without doing this can land you in real trouble. Either your database can become corrupted or you delete files or worse you lose everything because of some stupidity or other. Unfortunately this can happen. So make sure you perform the following steps first.
Before you upgrade your blog, always always backup your content. Thankfully because I run my blog on AWS this is easy. I take an EBS (Elastic Block Store) volume snapshot of my existing instance. This costs me a bit each month but it's really easy so I prefer the convenience over the cost.
Check your restart command
I was confident my restart command worked because due to my How to drive your Ghost Blog using Continuous Delivery series it constantly restarts on site updates anyway so I could safely skip this step.
Due to the fact that your database will need upgrading at each stage, you have to watch out for which version you can actually upgrade to. As of today these are Ghost's sensible instructions...
The changes between the version numbers in Ghost have significance. As we are still pre 1.0, semantic versioning doesn’t fully apply, but we try to make sure that patch version upgrades; e.g. 0.6.4 to 0.6.5 are safe, whereas bigger changes are indicated with a minor version bump; e.g. 0.6.4 to 0.7.0. If you’ve fallen really far behind, you might not be able to upgrade direct to the latest version.
If you’re going through a major version, e.g. 0.7.0, 0.8.0 or 0.9.0, be aware there are database migrations as part of the upgrade and Ghost can take a lot longer to start up again after the upgrade. It’s best to start Ghost using npm start --production the first time after these upgrades.
For blogs on version 0.5.0 or greater you should be able to upgrade to any 0.7.x version.
For blogs on version 0.4.2 (2 years old!) you must upgrade to Version 0.7.1 (0.7.0 had a couple of upgrade bugs which are ironed out in 0.7.1), before upgrading to any later 0.7.x version.
For blogs on anything before 0.4.2 you must do incremental upgrades until you get to 0.4.2.
So, I was previously on version 0.6.x so I was okay to upgrade directly to 0.8.x
However, if you're on a lower version make sure to check the instructions carefully to make sure you can jump to the semantic version you want.
Upgrading Your Version
Now that I was ready to begin there were just a couple more things I needed to do to upgrade to the right version.
Grab the version you want
I grabbed version 0.8.0 from the Github Releases Page as a zip file and unzipped it locally in the same folder as my /ghost install on my local machine.
Replace New Ghost Files
I then followed steps 3 and 4:
- Delete the old files
Navigate to your Ghost installation folder and delete the core directory. This contains most of the files which make up the Ghost software. Do not delete the content directory.
You can also delete the index.js file, and all the files ending with .md and .json. Do not delete your config.js file. You may prefer to leave these files, and just copy the new versions over the top. The important thing is to delete the whole of the core directory.
- Copy over the new files
Copy the core directory from your newly downloaded latest version of Ghost. Also be sure to copy & replace index.js, package.json and npm-shrinkwrap.json – getting the latest copies of these 3 files is critical to the upgrade completing successfully.
You may also want to copy over the latest versions of the .md files like README.md or PRIVACY.md so you have them to hand as these contain useful info.
If you’re using Casper – the default theme – without modifications then you’ll also want to copy the content/themes/casper folder from the latest version into place in your install directory.
cp -R path-to-unzipped-ghost-folder/content/themes/casper path-to-ghost-install/content/themes
Although, technically I could have not bothered copying over the Casper theme I did anyway for brevity.
Generate New Release
As part of my release procedure it's really straightforward. I can skip permissions, dependencies and restarting Ghost since the deploy github hook scripts that enable Continuous Deployment handle all this for me. All I needed to do was locally generate the zip archive using a shell script called
archive.sh which contains:
git archive -o ghost/archive/devangst-site-compressed.zip HEAD
Committing that file was really all that was required.
I love it when a plan comes together!
If you're interested about continuously deploying your Ghost blog check out my series on how to do it.