How do I upgrade my Mastodon server to the next version?

I've had trouble upgrading my software and I think this might have to do with the way everything was installed from the Marketplace here in Linode. Can anybody point me in the right direction for how to get started upgrading to the next version? Can I do it with apt-get?

16 Replies

I have the same Problem :-/ … the other instances with cloudron no problem! … Akamai, please give us an Upgrade-Tool-Kit :-*

Before upgrading, it's important to back up your data to ensure you can restore it if something goes wrong. Backup your Mastodon PostgreSQL database using the following command:

sudo -u postgres pg_dump mastodon_production > ~/mastodon_backup.sql

Change to the Mastodon user (optional): If you are not already operating as the mastodon user, switch to it by running:

sudo su - mastodon

Navigate to the Mastodon directory: Change to the Mastodon installation directory:

cd ~/live

Fetch the latest source code: Fetch the latest Mastodon release from the git repository:

git fetch --tags

Check for the latest version: List the available tags (versions) and identify the latest stable release:

git tag -l

Switch to the latest version: Check out the latest stable version (replace <latest-version> with the actual version number, e.g., v3.5.0):</latest-version>

git checkout <latest-version></latest-version>

bundle install && yarn install

RAILS_ENV=production bundle exec rails db:migrate

RAILS_ENV=production bundle exec rails assets:precompile

sudo systemctl restart mastodon-web.service mastodon-sidekiq.service mastodon-streaming.service

Your Mastodon server should now be running the latest version. Keep in mind that it's essential to monitor the upgrade process closely, as issues may arise during the process. If you encounter any problems, consult the Mastodon documentation or community support channels for assistance.

Thank you for those instructions!
I was disappointed to find out that this Marketplace app made by Linode comes with no upgrade instructions, frankly, I thought it would update itself. I contacted Linode support and they replied:

"Good morning,
When you deploy a Mastodon from the Marketplace we use a version that's tested and stable. In some cases that would be the latest release, but might not be depending on testing or emerging feedback from users. A Linode you've created from a Marketplace deployment is not automatically updated as the Marketplace simplifies getting started and doesn't imply automated support.
Because the nature of upgrading Mastodon releases might change in the future I'll refer to their guided instructions. I recommend proceeding if you feel technically capable, and creating a backup for your Linode prior to any manual installations."

They added a link to the official update instructions on mastodons website. those did not work for me and unfortunately the instructions that kamankay provided dont work for me.

I don't know the password for the user mastodon and if I try to check out the tag for the newest stable release it says:

mastodon@social:/home/mastodon/live$ git checkout v4.1.2 error: Your local changes to the following files would be overwritten by checkout: docker-compose.yml Please commit your changes or stash them before you switch branches. Aborting

It looks like you have made changes to the docker-compose.yml file and you need to deal with them before you can switch branches or checkout a new tag. You have a couple of options:

If you want to keep your changes and switch to the new branch/tag:

a. Stash your changes:

git stash save "My local changes"

b. Checkout the new tag:

git checkout v4.1.2

c. Apply the stashed changes to the new branch/tag (you might need to resolve conflicts if there are any):

git stash apply

If you want to discard your local changes and switch to the new branch/tag:

a. Reset the docker-compose.yml file to the latest commit in the current branch:

git checkout -- docker-compose.yml

b. Checkout the new tag:

git checkout v4.1.2

After you have switched to the new tag, you should be able to proceed with your work. If you encounter any issues, feel free to ask for more help!

Thank you so much! I’ll give that a try tomorrow. I did not knowingly change anything on the docker-compose file, this is the first time I’m logging in to that linode since deploying it. Let’s hope I won’t need the password for that mastodon user, I guess I could overwrite it since I can login with root but I don’t know if there is anything that depends on that pre-set password that I don’t know.

I’ll report back tomorrow, thanks again!


unfortunately I did not get too far, I'm not sure if I resolved conflict correctly, I don't really know how to use git :/

mastodon@social:/home/mastodon/live$ git stash apply 
HEAD detached at v4.1.2
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        deleted:    docker-compose.yml


mastodon@social:/home/mastodon/live$ bundle install && yarn install
-bash: bundle: command not found

I can restore my linode to the snapshot before I made any changes, in case you have an idea how to solve the issues above :) Thank you

The Marketplace Mastodon Application deploys Mastodon with Docker. You can check the status of the containers from the command line using the sudo docker ps command:

sudo docker ps -a
CONTAINER ID   IMAGE                       COMMAND                  CREATED       STATUS                    PORTS                                NAMES
bd4e0b360a54   tootsuite/mastodon:v4.1.2   "/usr/bin/tini -- ba…"   4 hours ago   Up 13 minutes (healthy)>3000/tcp, 4000/tcp   live_web_1
74b5c197562a   tootsuite/mastodon:v4.1.2   "/usr/bin/tini -- no…"   4 hours ago   Up 13 minutes (healthy)   3000/tcp,>4000/tcp   live_streaming_1
ce9549d5ff74   tootsuite/mastodon:v4.1.2   "/usr/bin/tini -- bu…"   4 hours ago   Up 13 minutes (healthy)   3000/tcp, 4000/tcp                   live_sidekiq_1
11df5478f07c   postgres:14-alpine          "docker-entrypoint.s…"   4 hours ago   Up 13 minutes (healthy)                                        live_db_1
66bf89a064bb   redis:7-alpine              "docker-entrypoint.s…"   4 hours ago   Up 13 minutes (healthy)                                        live_redis_1

With this in mind, the documentation on upgrading a Mastodon instance provided on is not relevant.

Instead, I suggest this guide by a Mastodon community user on upgrading your Docker deployment.

You can also check out the GitHub Discussion Forum where others have discussed upgrading their Docker instances for more advice.

It seems that the bundle command is not found, which means that the Bundler gem is not installed on your system or not in the system's PATH. To install Bundler, follow these steps:

First, make sure you have Ruby installed on your system. You can check this by running:

ruby -v

If Ruby is not installed, you can install it using:

sudo apt install ruby

Install the Bundler gem by running:

gem install bundler

Once Bundler is installed, run the commands again:

bundle install && yarn install

If you still encounter the "command not found" error, make sure that the gem binaries are in your system's PATH. You can do this by adding the following line to your ~/.bashrc or ~/.bash_profile file:

export PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"

After adding the line, restart your terminal or run source ~/.bashrc or source ~/.bash_profile to apply the changes. Then try running the commands again.

FWIW, this was the only guide that worked for me in trying to upgrade my instance with today's 4.1.3 security release:

(I might have been holding it wrong, but the community guide shared by @tlambert didn't work for me.)

Running into this frustration myself. Linode Akamai either needs to build the Marketplace app according to Mastodon's stock specifications exactly, or they need to provide proper upgrade instructions themselves. This is just silly.

Thanks everyone for your suggestions and help!
I had another two hours this morning to give all of those ways a try and none of them worked for me, I've reverted back to my snapshot that is still on v4.1.0

mastodon@social:/home/mastodon/live$ docker-compose run --rm web rails db:migrate
Starting live_db_1 … done
Starting live_redis_1 … done
Building web
ERROR: dockerfile parse error line 8: Unknown flag: link

One way or another I can't build the web part because the dockerfile is using --link which doesn't work for me and I can't figure out how to fix that or what to replace --link with.

Any ideas? Thanks!

Apparently simply removing every mention of --link should do the trick but there is a new error message 🙃

ERROR: Service 'web' failed to build: The command '/bin/bash -o pipefail -c OTP_SECRET=precompile_placeholder SECRET_KEY_BASE=precompile_placeholder rails assets:precompile && yarn cache clean' returned a non-zero code: 1

this keeps getting better and better. with all those issues like ruby not being installed on host, mastodon user not in Docker group etc, I'm actually surprised how they build this one-click app and I'm wondering if they later on removed stuff to shrink disk space. they definitely didn't intend for people to update this which is… bad.

ah npm wasn't installed on host which is why yarn didn't work 🙃


sudo apt install npm && sudo npm install -g yarn

and then

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

that worked better this time but now I'm getting python errors all over the place, so I'm reverting back to my v4.1.0 snapshot again :/

I just put up a step-by-step guide on upgrading a docker Mastodon deployment. For folks who used the Marketplace Mastodon Application it should really help with upgrades.

I used it to upgrade from v4.1.2 to v4.1.4 but you should be able to use the same process for other incremental upgrades as well.

@tlambert thank you so much! Your guide eventually worked for me, it took me a few tries because I ran out of disk space during image building and then restoring some snapshots did not work but I am finally on v4.1.5 now.

Can you please put a link to the guide and/or instructions on the one-click-app page here so that not all of us have to try and make this work for 3 months? I was so close to switching to a managed hosting solution.

I really appreciate your guide. Thanks!

Also thanks to everyone who commented on this post and helped me, if possible please mark @tlambert's post as the solution to my initial post.



Please enter an answer

You can mention users to notify them: @username

You can use Markdown to format your question. For more examples see the Markdown Cheatsheet.

> I’m a blockquote.

I’m a blockquote.

[I'm a link] (

I'm a link

**I am bold** I am bold

*I am italicized* I am italicized

Community Code of Conduct