Confusing instructions; clarification for ghost image

On the Ghost image site for Docker Hub under Upgrading Ghost, it has the following instructions:

For upgrading your Ghost container you will want to mount your data to the appropriate path in the predecessor container (see below): import your content from the admin panel, stop the container, and then re-mount your content to the successor container you are upgrading into; you can then export your content from the admin panel.

https://hub.docker.com/_/ghost

I find these instructions extremely confusing…

Can anyone shed some light on why they are written in this way, or clear up what I am misunderstanding?

Mount your data to the appropriate path in the predecessor container

Why would one need to mount their data to the appropriate path in the predecessor container–wouldn’t that be done already if they had a functioning Ghost container to upgrade?

Import your content from the admin panel, stop the container

Why would one need to import content from the admin panel and stop the container (again, this is already done; but if the intention here was to tell people to backup their data before doing the upgrade, then shouldn’t the instruction be to export your content from the admin panel, then stop the container)?

Re-mount your content to the successor container you are upgrading into

This makes sense to me.

You can then export your content from the admin panel

Why would one need to do this?

If this instruction is to import previously exported content via the admin panel, it would make sense, but if we’re mounting the content, why would it need to be imported again?

If it is written correctly, then what is the point of exporting the content? Is this just to make a back-up?

Thanks in advance for helping me understand the procedure.

Is there a reason that you skipped the motivation for the data migration in your post?

You will want to ensure you are running the latest minor version (1.25.5 or 0.11.9) of Ghost before upgrading major versions. Otherwise, you may run into database errors.

Seems like this is a strategy to ensure a stable update between major version updates. And it feels like they mixed up export from the old version and import in the new version - the page says to do the opposite…

Whatever you do, make sure to make a backup of your volume before :slight_smile: A simple tar cvfz backup.tar.gz /path/to/bind-mount/folder/ (or however you do your backups) should do the trick and allows to reproduce the migration until it succeeds…

@meyay thanks for your response.

I am trying to learn more about Docker (learn by doing) with small projects. I figured one of the first tools I should use to explore was Ghost, as it is one of the curated Official Docker Images, and I assumed the documentation would be clear and easy to understand.

My motivation with the upgrade is to understand how to perform upgrades of software in Docker containers, and to keep my Ghost container up-to-date. It seems like it should be pretty easy, but there’s obviously data associated–schemas can change–and it’s not clear to me how that’s handled.

My other motivation is simply to correct the documentation, because I’ve thought about this for a long time and can’t make sense of it. If they mixed up import and export, it can be easily corrected. Also, it is not clear that this procedure is only necessary between major versions. I would consider a minor version increment an upgrade, and I think most other sysadmins would too.

Thanks for your tip to tar the content folder before the upgrade.

Lerning by doing is the only way how it sticks :slight_smile: If you want to broaden your docker knowledge, this self paced training is highly recommended.

A container is always created from a specific version of an image (even if a mutable tag like “latest” is used, it still points to the specific version of the image and not to the latest image the tag is pointing to) . In order to create a container from an updated image, you need to remove the old container, pull the new image (if the tag exists in the local cache, the updated image doesn’t get pulled) and create a new container based on the new image.

As far as I understand, the section of the Dockerhub description specifically covers major version upgrades, as it instructs to perform all minor version updates before the major update is performed. It smells like the image maintainer prepares us for breaking changes that justify this cumbersome migration method.

I share your opinion regarding the mixup of import and export. It is a good idea to raise an issue on Github for the doku fix.

What I realy like about taring the folders is, that the archive will retain ownership, permissions and a well known state of your data. You can recreate the starting point of your migration as often as necessary.

The luxuries of the statelessness of containers. I suppose that is the appeal. Thanks!