How do I Upgrade my Mastodon Docker Deployment?

The Marketplace app is set to pull the latest Mastodon version at the time of deployment. That means you will need to upgrade to any newer releases manually. By following these steps, hopefully the process will be relatively straightforward. It's worth noting I upgraded from v4.1.2 to v4.1.4 using this process.

Like with any major changes to your system, the first thing you should do is create a full backup. I suggest the Linode Backups Service because it's simple, reliable, and creates multiple automatic backups in addtion to giving you the option to create a Snapshot.

Next, SSH into your server and ensure your system is up to date:

$ sudo apt update && sudo apt upgrade

Reinstall Docker Engine

For some reason, the version of docker that's pre-installed on the Marketplace deployment will not upgrade Mastodon version out of the box. If you don't reinstall the Docker Engine, you'll get an error trying to build the new services. You need to uninstall previous docker packages and reinstall the latest version:

$ for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Backup your Database

Next, you want to create a backup of your database. Switch to the mastodon user and, change to the /home/mastodon/live directory and find the database container. It should be named live_db_1.

$ su mastodon
$ cd /home/mastodon/live
$ sudo docker ps -a

Use this command to connect to create a backup of your database on the container, changing <$date> to the date you're creating the backup for tracking purposes:

$ sudo docker exec -it live_db_1 /bin/bash -c 'pg_dumpall -U mastodon -f db_backup-<$date>.sql && exit'

Copy the backup to your host:

$ sudo docker cp live_db_1:/db_backup-<$date>.sql /home/mastodon/

If the dump was successful, the tail output of your db_backup-<$date>.sql will look like this:

SET row_security = off;

--
-- PostgreSQL database dump complete
--

--
-- PostgreSQL database cluster dump complete
--

Upgrade to the New Release

Now it's time to upgrade your containers to the newest release using a series of git and docker commands from the /home/mastodon/live directory.

Fetch the version tags from the remote and stash the changes to your working directory.

$ git fetch --tags
$ sudo git stash

Use this command to switch to the latest version:

$ sudo git checkout v4.1.4

You will likely see some errors here but they'll be cleaned up in the next step.
Check for modified files in the working directory

$ sudo git stash pop

Use the following command to discard any changes you made to files in the working directory:

$ sudo git restore <modified files>

Once you have discarded the changes that showed up when you initially ran git stash pop, run it again to ensure no other files need to be restored.

Build the Web, Streaming and Sidekiq services:

$ sudo docker compose build

Check for recently created images - you should see the image you just created at the top:

$ sudo docker images

Run the pre-deployment database migrations:

$ sudo docker compose run --rm -e SKIP_POST_DEPLOYMENT_MIGRATIONS=true web rails db:migrate

Check the success of the migration with echo $?. If the output is 0 then the migration was successful.

Shutdown all docker-compose services

$ sudo docker compose down

Clear the cache:

$ sudo docker compose run --rm web bin/tootctl cache clear

Run post-deployment database:

$ sudo docker compose run --rm web rails db:migrate

Once again, if the output of echo $? is 0, the migration was successful.

Create and start the docker containers:

$ sudo docker compose up -d

Remove any unused docker data. This will get rid of any images or containers not in use with your mastodon deployment so use with caution:

$ sudo docker system prune -a 

Once you've completed these steps, you should see the newest version of Mastodon in the footer of your instance's homepage.

Special thanks to Floris Van den Abeele and their work in this post titled Upgrading your mastodon instance, where I a lot of the info for this guide.

thank you for writing this guide @tlambert, this worked for me.

please link it one the one-click-app/linode app page.

Thanks!

@MariusQuabeck - we got the link added to the Marketplace App page shortly after this was posted. Thanks for the suggestion!

Sorry … it doesnt work!
Is that Upgrade for Debian11 Install?

I get only Errors. I cant Upgrade from Mastodon V4.0.2 to V4.2.1 … i give up and search for an other Provider with easy Update-Service. Thats not fine …

Thanx for your support. But the Step by Step manual doesnt help … me.
Liebe Grüße … Sven

@arkmix - I just ran through this process again on the instance I deployed through the marketplace 3 months ago and it worked. I was able to upgrade from v4.1.4 to v4.2.1 without a problem.

The default distro is Debian 11 so if you've used a different installation process, you may get a different result.

You said,

"I get only Errors."

What kind of errors are you seeing? I mention that you need to reinstall Docker Engine for these instructions to work correctly since the version of Docker installed in the Marketplace App won't update Mastodon out of the box. Did you follow this step?

I can confirm @tlambert, the guide has been working for me, for the Linode Marketplace App, since it was published and I was able to Update to newer versions ever since.