What is this?

If you are self-hosting like I am then the Ghost upgrades are not automatic as they would have been if you were hosting with Ghost(Pro). Luckily the tutorial for this is pretty straight forward and this post will help you avoid some common gotcha's that you may encounter when following the official Upgrade Tutorial from Ghost.

WHAT TO UNDERSTAND

  • Always, always, always back-up your ghost blog before you start!
  • All commands below are run as root

REMEMBER: if you are not familiar working in root you can use your regular unix account and just put 'sudo' in front of each command you run

Ok, let's do it! - here are the commands:

(1) Get the latest version:

curl -LOk https://ghost.org/zip/ghost-latest.zip OR a specific version curl -LOk https://ghost.org/zip/ghost-<version>.zip

(2) Unzip to a temporary location:

unzip ghost-latest.zip -d ghost-temp

(3) Change directory into your current ghost install:

cd path-to-ghost-install, E.g. cd /var/www/ghost

(4) Remove the core directory completely:

rm -rf core

(5) Change back to your download of Ghost latest:

cd path-to-ghost-temp E.g. cd ~/Downloads/ghost-temp

(6) Copy the new core directory to your Ghost install:

cp -R core path-to-ghost-install

(7) Copy the other key files to your Ghost install directory:

cp index.js *.json path-to-ghost-install

(8) (optional) Update Casper by copying the casper folder:

cp -R content/themes/casper path-to-ghost-install/content/themes

(9) Change back to your ghost install directory:

cd path-to-ghost-install

(10) (optional) Update permissions:

E.g. chown -R ghost:ghost *

(11) Upgrade dependencies:

npm install --production

(12) Restart Ghost

E.g. service ghost restart or forever restart index.js or pm2 restart ghost or npm start --production

All these commands came from this great Ghost tutorial that you can take a look at if you want to go more in-depth: http://support.ghost.org/how-to-upgrade/#command-guide

THE GOTCHA'S

Below three issues are what most people seem to stumble upon when they are upgrading

① WARN unmet dependency - This is a warning and shouldn’t cause problems. However it can mean that npm install didn’t complete properly. If you have other issues after seeing this message, use the fix for general npm install errors:

  • rm -rf node_modules
  • npm cache clean
  • npm install --production

② npm WARN cannot run in wd - If npm was invoked with root privileges, then it will change the uid to the user account or uid specified by the user config, which defaults to nobody. NPM basically tries to downgrade its privileges when it runs scripts. That downgrading of the privileges causes this error. Solution: Run npm install with the --unsafe-perm flag:

  • npm install --unsafe-perm

More about this is explained here:
http://stackoverflow.com/questions/18136746/npm-install-failed-with-cannot-run-in-wd#19132229
And this guy does a good job at explaining it too:
How to fix Npm install failed with "cannot run in wd" by Manu

③ npm install ends with killed - npm install ran out of memory and was unable to complete. You’ll need to increase the virtual memory available to npm. Example instructions on how to do this on DigitalOcean can be found in this post I wrote a while back: How To Increase Memory On A DigitalOcean Droplet Using Swap

TROUBLESHOOTING

This is a great troubleshooting page to quickly find error messages and what the fix is, when upgrading Ghost: http://support.ghost.org/troubleshooting

ADDITIONAL INFORMATION

NPM

When you get to item 11 in the tutorial Command Guide

11.Upgrade dependencies:
npm install --production

If you run as 'root', I find that instead of running the npm install --production command, it is better to use below:

rm -rf node_modules && npm cache clear && npm install --production --unsafe-perm

Which is a combination of ① and ② above. This avoids all the gotcha's.

Reference Links:
http://support.ghost.org/troubleshooting
http://support.ghost.org/how-to-upgrade/#command-guide
https://til.codes/npm-install-failed-with-cannot-run-in-wd-2
http://stackoverflow.com/questions/18136746/npm-install-failed-with-cannot-run-in-wd#19132229
https://www.digitalocean.com/community/tutorials/how-to-install-an-upstream-version-of-node-js-on-ubuntu-12-04