How to upgrade Mastodon

Mastodon upgrades change the application code that serves the web UI, background jobs, streaming API, and database schema. A server administrator should treat each release as a planned change window because release notes can require dependency updates, migrations, asset compilation, or service restarts.

Source installs normally keep application code under /home/mastodon/live with the mastodon Linux user and systemd units named mastodon-web, mastodon-sidekiq, and mastodon-streaming. Docker-based instances follow the same release-note discipline but replace the source checkout and systemd steps with the container image and Compose commands listed for the release.

The upgrade run starts with a restorable database and secret backup, records the starting version, checks out the target tag, runs only the upgrade tasks required by the skipped releases, and verifies the running version through both the CLI and the public web endpoint.

Steps to upgrade Mastodon:

Open the release notes for the target Mastodon tag.
```
https://github.com/mastodon/mastodon/releases/tag/v4.6.2
```
Replace v4.6.2 with the release being installed. When skipping patch releases, read the release notes for every skipped minor version series before running any upgrade commands.
Create a PostgreSQL backup before changing the application code.
```
$ sudo -u mastodon pg_dump -Fc mastodon_production -f /home/mastodon/mastodon_production-before-v4.6.2.dump
```
Keep the matching .env.production file, local /home/mastodon/live/public/system media or object-storage snapshot, and Redis dump with the same upgrade checkpoint.
Related: How to back up a Mastodon server
Switch to the Mastodon application user.
```
$ sudo -iu mastodon
```
Change into the source install directory.
```
$ cd /home/mastodon/live
```

Record the currently running Mastodon version.

$ RAILS_ENV=production bin/tootctl --version
Mastodon v4.6.1

Fetch the upstream release tags.

$ git fetch --tags
From https://github.com/mastodon/mastodon
 * [new tag]         v4.6.2     -> v4.6.2

Check out the target release tag.
```
$ git checkout v4.6.2
HEAD is now at 70d39d3 Update FFmpeg in container images
```
Do not continue on an unreleased main checkout unless the instance intentionally runs a maintained fork. Mastodon release upgrades should use published git tags.
Install Ruby dependencies when the target release notes list a dependency step.
```
$ bundle install
```
Patch releases may not need dependency installation. Run this step only when the release notes include it or when Gemfile.lock changed for the target tag.
Install JavaScript dependencies when the target release notes list a frontend dependency step.
```
$ yarn install --immutable
```
Frontend dependency changes and missing node_modules can leave the web UI without current compiled assets.
Precompile assets when the target release notes require it.
```
$ RAILS_ENV=production bundle exec rails assets:precompile
```
Run pre-deployment migrations when the target release notes require database migrations before restart.
```
$ SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
```
If PgBouncer sits in front of PostgreSQL, run migration commands against the real PostgreSQL port. Transaction-pooling ports can break Rails advisory locks during Mastodon migrations.
Return to the sudo-capable shell for service control.
```
$ exit
```

Restart the Sidekiq workers.

$ sudo systemctl restart mastodon-sidekiq

Reload the web process.
```
$ sudo systemctl reload mastodon-web
```
systemctl reload mastodon-web performs a phased restart for the web process. Use restart only when the release notes or local service state requires a full stop and start.
Restart the streaming API when the release notes mention a streaming restart.
```
$ sudo systemctl restart mastodon-streaming
```
Restarting mastodon-streaming disconnects connected clients. Expect a short reconnection burst as clients reconnect or fall back to polling.
Return to the Mastodon application user after the services are back.
```
$ sudo -iu mastodon
```
Change into the source install directory again.
```
$ cd /home/mastodon/live
```
Run post-deployment migrations when the target release notes require them.
```
$ RAILS_ENV=production bundle exec rails db:migrate
```
Keep this command separate from the pre-deployment migration. Some releases intentionally split schema preparation from post-restart backfills.
Confirm that the application code reports the target version.
```
$ RAILS_ENV=production bin/tootctl --version
Mastodon v4.6.2
```
Return to the sudo-capable shell after the CLI version check.
```
$ exit
```

Check that the Mastodon services are active.

$ systemctl is-active mastodon-web mastodon-sidekiq mastodon-streaming
active
active
active

Request the public Mastodon web endpoint.
```
$ curl -I -sS https://social.example.com/about
HTTP/2 200
content-type: text/html; charset=utf-8
x-request-id: 1c8f6ff0-7f3a-4c20-9d8c-90a2c13b2481
##### snipped #####
```
Use the real instance hostname and a page that should be reachable by anonymous users. Keep the request ID when investigating a failed response because Mastodon logs include the same identifier.

Author: Mohd Shakir Zakaria
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.