Upgrading to a new release
mainbranch, while possible, is not recommended.
Since v4.2.0, Mastodon will automatically check for available updates and notify the users of your server that have the
This happens by fetching
https://api.joinmastodon.org/update-check?version=<current_version> in the background every 30 minutes.
current_version omits the build metadata (everything after the first
+, if there is one, in the version string). For instance, if your version is
4.3.0-beta2+my-fork, Mastodon will query
You can change which URL Mastodon queries by setting the
UPDATE_CHECK_URL environment variable. You can also completely disable this behavior by setting this environment variable to an empty string, although we strongly recommend against doing that unless you are keeping up with Mastodon updates in another way, as Mastodon occasionally releases critical security updates that must be applied in a timely fashion.
Mastodon releases correspond to git tags. Before attempting an upgrade, look up the desired release on the GitHub releases page. The page will contain a changelog describing everything you need to know about what’s different, as well as specific upgrade instructions.
To begin, switch to the
su - mastodon
And navigate to the Mastodon root directory:
Download the releases’s code, assuming that the version is called
git fetch --tags git checkout v3.1.2
Now execute the upgrade instructions that are included in that version’s release notes on GitHub. Because different releases require different instructions, we do not include any instructions on this page.
After you have executed the instructions from the release notes, switch back to root:
Restart background workers:
systemctl restart mastodon-sidekiq
And reload the web process:
systemctl reload mastodon-web
reloadoperation is a zero-downtime restart, also called “phased restart”. As such, Mastodon upgrades usually do not require any advance notice to users about planned downtime. In rare cases, you can use the
restartoperation instead, but there will be a (short) felt interruption of service for your users.
The streaming API server is also updated and requires a restart, doing so will result in all connected clients being disconnected, which can increase load on your server:
systemctl restart mastodon-streaming