How to upgrade an instance to Mastodon 4.3
Posted by:
-
Konstantin
09/10/2024: This guide has been updated to facilitate migrations to Mastodon 4.3. Please, also check the the official guide for more technical insights.
The Mastodon documentation contains an excellent overview of the upgrade process. It is based on that that I created this guide. It's aimed at solo and very tiny-instance folks.
Don't forget to back-up before going any further!
The upgrade process described bellow will result in instance downtime. If others are also using it, make sure to make them aware that the app will be temporarily unavailable.
Our first step is to shut down the currently running instance.
systemctl stop mastodon-*Then, we switch to the default mastodon user and navigate to mastodon root directory (the /live folder)
sudo - mastodon -s /bin/bash
cd ~/liveFirst, we need to download the new version and make sure the correct local Ruby version is installed.
git fetch
git checkout v4.3.1
rbenv install $(cat .ruby-version) --verboseSince version 4.3, Mastodon uses corepack. To enable it, run the following in the `~/live` folder:
corepack enable
corepack prepareMastodon now requires that these variables are set:
- ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
- ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT
- ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
There is a script provided to help create them. Let's run the following:
RAILS_ENV=production bin/rails db:encryption:initThe command will complete by printing each secret. Update your `.env.production` file to include them!
Tip: You can use a text editor like `nano` to open .env.production and append the new variables at the bottom. The output of the db:encryption:init command already formats them correctly so all you need to do is copy paste!
Before you continue, please make sure that you've upgraded NodeJS as per Mastodon's requirements to version 18 or the latest stable release.
The following commands upgrade the database and rebuild the Mastodon assets to their latest version.
bundle install
rm -rf node_modules && yarn install --immutable
SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
yarn build:production
RAILS_ENV=production bundle exec rails assets:precompileFinally, we need to start all Mastodon services. Use the exit command to exit the mastodon user session and go back to the system user. Then run the following:
sudo systemctl restart mastodon-sidekiq.service
sudo systemctl restart mastodon-web.service
sudo systemctl restart mastodon-streaming.serviceSince Mastodon 4.3, there is an additional script to execute after starting the Mastodon services. Please execute the following command:
RAILS_ENV=production bundle exec rails db:migrateNext, we need to rebuild the elastic search index
RAILS_ENV=production bin/tootctl search deploy --only=accountsAnd voilà 🎉! You should be able to access your instance.
If this tutorial was helpful, or you have recommendations or suggestions to improve it, feel free to send an email or reach me via one of the socials below!
