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
$ 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
docker commands from the
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.
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.
"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?