Documentation on updating Ghost

[ErisDS]

With the release of Ghost v5 we have spent quite a lot of time carefully crafting update docs

https://ghost.org/docs/update

However, they are for the recommended install method which is Ghost CLI. We use the CLI to do a lot of the legwork and prevent issues with updates.

With docker, I'm not sure there's any way we can do anything to prevent people updating incorrectly, but it seems there should probably be detailed update docs?

The critical details being:

1. mysql8 is now the only supported database in production.
2. updates across majors are only guaranteed to work if you update to the latest version in your major first.

To clarify that last point, if you're on 3.25.9, you need to update Ghost to 3.42.9 - including starting the server to trigger the migrations - before updating to v5.0.0.

Note: you don't have to cycle through every major - you don't have to upgrade to v4 first.

There's absolutely no way to guarantee you can update from any version to any version without data loss or corruption as there can always be bugs that are fixed in later versions 🤷‍♀️

[tianon]

Yeah, this type of upgrade is a little bit complicated all around 😬

I think the best I can suggest is maybe a little blurb added to the very top of https://github.com/docker-library/docs/blob/master/ghost/content.md (maybe moving up the existing "Upgrading Ghost" section)?

Does it already / do you think it would be possible/reasonable to have the newer versions balk with a useful error message on startup/migration if you haven't done this, perhaps linking to those docs? 😅

[elliotblackburn]

I've just completed two docker based ghost upgrades and it was flawless. I thought I'd note down my approach for anyone who might find it useful, I'm not sure how useful it'll be for the future documentation proposed but maybe it'll help a little.

I'm using docker-compose for them both so here's the steps I went through.

1. Take a backup of the site in question first. For me it was enough to just get a json export dump which I've happily restored from in the past.
2. Update the MySQL container to mysql:8.0.29, if you're using a different flavour YMMV. I did a full restart using docker-compose down && docker-compose up -d && docker-compose logs -f to allow the DB to come up from 5.x to 8 and then did a quick test that everything was still ok.
3. Update to the top version of the major I was on. For me this was a case of going from 4.44-alpine to 4.48-alpine. Same deal command as above to do a full restart and another quick manual test.
4. Update to ghost:5.0.2-alpine, another full restart using the docker-compose command above followed by another manual test.

This process worked for me with the various container versions above for two seperate sites on a dedicated Ubuntu 21.10 (GNU/Linux 5.13.0-41-generic x86_64) machine.

My final docker-compose file for both sites is:

version: '3.7'

services:

  ghost:
    image: ghost:5.0.2-alpine
    restart: always
    depends_on:
      - db
    ports:
      - "127.0.0.1:3400:2368"
    volumes:
      - ./content:/var/lib/ghost/content
      - ./config.json:/var/lib/ghost/config.production.json
    env_file:
      - ./db.env

  db:
    image: mysql:8.0.29
    restart: always
    volumes:
      - ./data:/var/lib/mysql
    env_file:
      - ./db.env

(This fits my needs, other people may need ports and volumes configured slightly differently).

Hopefully this helps in someway!

Edit: I've expanded on this comment in a blog post. It covers a few approaches for taking a backup amongst other things You can find it here - https://www.elliotblackburn.com/upgrading-to-ghost-5/

[ErisDS]

I just want to be clear, Ghost team are responsible for maintaining Ghost-CLI which already has protections built-in to make sure updates are smooth and correct.

Our small team doesn't currently have capacity to also manage the docker process, and we don't use docker much as a team/org, so we aren't best placed to do the work either 😬

If anyone wants to get creative with changes to Ghost to prevent bad updates, I'm totes here for code reviews and merges though. If someone is up for writing a proper upgrade guide, I'm also happy to link to it from the official docs 🙂

[kihashi]

Might also be worth adding a note about not pinning latest. Lots of Docker guides just say to pull that without considering later updates where this might cause problems. For Ghost, if you're constantly updating to latest, that's not really an issue, but if you wait and a major version is released, you'll potentially run into issues.

I'm not sure if it would be considered "On Topic" for this section, but it might also be a good idea to mention breaking changes like #323. Arguably, this is called out in Ghost's documentation directly, but somehow I still managed to miss that I should have moved to MySQL as part of the 5.0 update and only found out when updating minor versions thanks to someone on twitter who pointed me to that PR. Given that the officials docs recommend "Full Reinstall" for the migration, I think it would be worthwhile to point out what that migration path looks like for Docker users.

If folks would like, I'd be happy to work on a PR to that effect or at least write up what I learned doing mine.

[CaptainStack]

I would like to chime in - I am looking to try out Ghost and so far have not been able to install it. On one hand, I tried to install locally using Ghost-CLI but ran into the issue of being on Node 19, with Ghost only supporting Node 18 and lower. Since in the past I've had a huge pain managing different Node versions and really prefer to stay on the latest stable branch, I thought okay I'll try the Docker image - I mean it's suggested right there in the docs.

Unfortunately the docs are out of date and the image doesn't work (getting "Unknown database error").

Given that you're not on the latest version of Node I would think support for the Docker image would be doubly important as it gives developers a way to know they are on the right version without worrying. So far I haven't been able to get started with Ghost which is too bad because I really like the idea of a modern NodeJS based CMS.

[elliotblackburn]

I've put together a slightly more thorough guide for the upgrade from Ghost 4 to 5 on my blog. It's an expansion of what I wrote in my prior comment but I've walked through the process with a test blog again and tried to make it slightly more accessible. I've included a starting state and ending state along with some of the notes @ErisDS mentioned.

You can find it here: https://www.elliotblackburn.com/upgrading-to-ghost-5/

Please excuse the poor colours on dark mode, it looks like the theme doesn't have great colour choices for code snippets there. All the content is there but light mode might make for better reading until I can make the fix later today.

I could put together another walk through of setting up a ghost blog from scratch via docker-compose if that would be useful to anyone. It would be mostly just explaining the yaml file I'm using and linking out to the ghost docs for customisation. I don't think it's unreasonable for the Ghost team to say they don't support this method of deployment right now though. They only have limited resources after all and can't tackle everything. The notes they've provided in this issue are already going beyond their stated official support.