Note: This is a release candidate. It is intended to be stable, but not guaranteed.

Upgrade overview

This release contains upgrade notes that deviate from the norm:

ℹ️ Requires two-step database migration process for zero-downtime deployment ℹ️ Some migrations may take a long time to run ℹ️ Behaviour of AUTHORIZED_FETCH changed ℹ️ Requires review of Sidekiq queues in some setups. This also applies to updating from v4.0.0rc2

For more information, scroll down to the upgrade instructions section.

Changelog

TBD. This update includes a variety of fixes and improvements on top of v4.0.0rc1.

Upgrade notes

To get the code for v4.0.0rc3, use git fetch && git checkout v4.0.0rc3.

As always, make sure you have backups of the database before performing any upgrades. If you are using docker-compose, this is how a backup command might look: docker exec mastodon_db_1 pg_dump -Fc -U postgres postgres > name_of_the_backup.dump

Update steps

The following instructions are for updating from 3.5.3.

If you are upgrading directly from an earlier release, please carefully read the upgrade notes for the skipped releases as well, as they often require extra steps such as database migrations.

Non-Docker only:

• The recommended Ruby version has been bumped to 3.0.4. You can upgrade, or you can continue using the old version by overwriting the .ruby-version file with e.g. 3.0.3 which was recommended previously
• Install dependencies: bundle install and yarn install

Both Docker and non-Docker:

:warning: Incoming federated activity now uses a new ingress queue in Sidekiq. If you customize Sidekiq processes/queues, ensure that there is at least one process handling the ingress queue.

1. Run the pre-deployment database migrations by specifying the SKIP_POST_DEPLOYMENT_MIGRATIONS=true environment variable:
   • Non-Docker: SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
   • Docker: docker-compose run --rm -e SKIP_POST_DEPLOYMENT_MIGRATIONS=true web rails db:migrate
2. Precompile the assets:
   • Non-Docker: RAILS_ENV=production bundle exec rails assets:precompile
   • Docker: The assets are already precompiled during the build step
3. Restart all Mastodon processes
4. Now that the new code is running, we can finish the database migrations. This will run the post-deployment ones:
   • Non-Docker: RAILS_ENV=production bundle exec rails db:migrate
   • Docker: docker-compose run --rm web rails db:migrate
5. Restart all Mastodon processes

For all notes, see v4.0.0rc1. This update includes a variety of fixes and improvements. Upgrading from v4.0.0rc1 requires a code update, assets precompilation, and a web process reload/restart.