Upgrading Ghost to 0.11.4

Hosting your own Ghost blog might have some disadvantages (from a consumer standpoint) but as I've previously mentioned - I like to fiddle with stuff.
So now it's time to upgrade my blog to the newest version of Ghost. Manually.

The folks from Ghost have a pretty handy tutorial on doing that but if you have a similar setup1 to mine you might as well follow this post. (Some of my steps are exactly the same)

  1. Before upgrading
    1.1. Consider the upgrade
    1.2. Backup your stuff
    1.3. Check your restart command
  2. Upgrade
    2.1. Download the latest Ghost version
    2.2. Extract the latest version somewhere
    2.3. Delete the old files
    2.4. Copy the new files
    2.5. Check file permissions
    2.6. Update project dependencies
    2.7. Restart Ghost
  3. Troubleshooting

Before upgrading

Some things to go through before starting the upgrade process. The second step on the list is the most important one.

1. Consider the upgrade

Ghost is still heavily in development, so big changes from version to version might occur and might break... everything. Read carefully through the release notes and change log and if something suggests you might break something, then you'll have to think about upgrading.

As I'm upgrading from 0.11.3 to 0.11.4 I'm not supposed to experience any problems, so I'll go for it. (Also, it's my first time upgrading this instance and I want to see how painless it would be)

2. Backup your stuff

If you don't regularly backup your stuff (I don't... I should probably set up a cron or something to automatically make backups for me), now is the time to make one.

Use the export tool in the Labs tab (Under settings). That will create a .json file with some of your data. After that, copy your whole content folder somewhere you won't touch it.

cp -r ghost/content/ ~/content_backup  

3. Check your restart command

If you haven't already restarted your ghost blog, now is a good time to learn how to do it. Fortunately, it's really straightforward in Ubuntu - you can just use the service command.

service ghost restart should do the trick.

Upgrade

1. Download the latest Ghost version

The first step of the actual upgrade would be to download the latest Ghost version. Unless you want to downgrade or upgrade to a particular version, you should always be able to get the latest version with:

curl -LOk https://ghost.org/zip/ghost-latest.zip  

2. Extract the latest version somewhere

After downloading the latest version, unzip (unarchive) it to a new (temporary) location. Important - do not unzip the new version on top of the old one, things can get messy really fast.

unzip ghost-latest.zip -d ghost-latest  

3. Delete the old files

Again, before deleting anything make sure you have backups of what's important to you. That would usually be the content folder. (We won't be deleting it but just in case)
Delete the core folder (I had custom stuff in it and then I lost it, read more in the Troubleshoot section in the end of this post). You can either delete or directly overwrite the index.js file and any .md and .json files you might have. DO NOT touch config.js

4. Copy the new files

Now from the unarchived folder copy the core folder to your main ghost folder. Next, copy and replace index.js, package.json and npm-shrinkwrap.json. Those are the ones that will make the "magic" happen.

It's a good idea to copy the latest README.md and PRIVACY.md. Even more, if the upgrade you're making is a newer version.

5. Check file permissions

Assuming you're using the DigitalOcean setup I'm using, you'll need to update the new files' permissions. They have to be owned by the ghost user, which runs Ghost.

chown -R ghost:ghost core  

This will update the permissions on the core directory.
If your setup differs somehow, just make sure all of the files in the ghost directory are owned by the same user.

6. Update project dependencies

It's time for magic!

npm install --production  

This will hopefully install all of the ghost dependencies. Make sure you run this command in the ghost directory (the one where you can see core and content folders).

If anything goes wrong (e.g. errors happen, not warnings) - delete the node_modules folder, then run npm cache clean and then run the npm install command again.

If you still can't seem to install all of the dependencies, you might want to add a swap file to your system (Check the Troubleshoot section at the end of this post) or check the npm-debug.log file for more information on your particular error.

7. Restart Ghost

After successfully updating your dependencies, you should be set!

service ghost restart  

Troubleshooting

I ran into only two problems while/after upgrading.

The first had to do with npm install --production failing because of insufficient memory (current droplet has only 512MB RAM). By default, there's no swap file2 so you have to create a new one. You can follow the tutorial over here. (Note: I made my swap file 1GB big, just in case)

The second problem was that I lost my subscribe page completely because the subscribe page's template is located in the core folder of ghost so I deleted it completely. Since I wanted a custom view of that page and I wanted to use my own signup form (actually using MailChimp's) I naively decided to edit the existing subscribe view in place and then forgot to back it up.
Luckily Google cached my subscribe page 2 days ago, so I was able to copy the cached page's source.

For anything else, you can check out Ghost's official Troubleshooting Guide.

  1. DigitalOcean Droplet, Ubuntu 16.04.1 x64, Pre-installed Ghost

  2. Swap files are files that the system uses as an additional (virtual) memory in addition to the physical RAM.