Mastodon Server Upgrades

Overview

This provides a guide for upgrading specific versions.

Backup Instructions

These instructions backup the database and environment variables file. It does not back-up media files.

1. Create new directory called backups/<DATE>.
2. Copy live/.env.production to backups/<DATE> directory.
3. Dump database pg_dump -Fc mastodon_production -f /home/mastodon/backups/<DATE>/backup.dump

Versions

3.4.1

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file.
3. Fetch tags - git fetch --tags
4. Checkout 3.4.1 tag - git checkout v3.4.1
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Migrate DB - RAILS_ENV=production bundle exec rails db:migrate
8. Precompile Assets - RAILS_ENV=production bundle exec rails assets:precompile
9. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.4.2

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file.
3. Fetch tags - git fetch --tags
4. Checkout 3.4.2 tag - git checkout v3.4.2
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Migrate DB - RAILS_ENV=production bundle exec rails db:migrate
8. Precompile Assets - RAILS_ENV=production bundle exec rails assets:precompile
9. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.4.3

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.4.3 tag - git checkout v3.4.3
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Migrate DB - RAILS_ENV=production bundle exec rails db:migrate
8. Precompile Assets - RAILS_ENV=production bundle exec rails assets:precompile
9. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.4.4

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.4.4 tag - git checkout v3.4.4
5. Precompile Assets - RAILS_ENV=production bundle exec rails assets:precompile
6. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.4.5

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.4.5 tag - git checkout v3.4.5
5. Install Ruby dependencies - bundle install
6. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.4.6

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.4.6 tag - git checkout v3.4.6
5. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.4.7

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.4.7 tag - git checkout v3.4.7
5. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.5.0

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Checkout 3.5.0 tag - git checkout v3.5.0
4. Update available rbenv version - git -C /home/mastodon/.rbenv/plugins/ruby-build pull
5. Install Ruby 3.0.3 - RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.3
6. Install Ruby dependencies - bundle install
7. Install JS dependencies - yarn install
8. Run predeployment DB migration - SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
9. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
10. Update service files - cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
11. Reload systemd daemon - systemctl daemon-reload
12. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming
13. Clear cache - RAILS_ENV=production bin/tootctl cache clear
14. Run postdeployment DB migration - RAILS_ENV=production bundle exec rails db:migrate
15. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.5.1

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.5.1 tag - git checkout v3.5.1
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
8. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.5.2

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.5.2 tag - git checkout v3.5.2
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Run predeployment DB migration - SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
8. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
9. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming
10. Run postdeployment DB migration - RAILS_ENV=production bundle exec rails db:migrate
11. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

3.5.3

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 3.5.3 tag - git checkout v3.5.3
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
8. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.0.0

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Upgade NodeJS - curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - && sudo apt-get install -y nodejs
4. Install Ruby 3.0.4 - RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.4
5. Fetch tags - git fetch --tags
6. Checkout 4.0.0 tag - git checkout v4.0.0
7. Install Ruby dependencies - bundle install
8. Install JS dependencies - yarn install
9. Run predeployment DB migration - SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
10. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
11. Update service files - cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
12. Reload systemd daemon - systemctl daemon-reload
13. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming
14. Run postdeployment DB migration - RAILS_ENV=production bundle exec rails db:migrate
15. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.0.2

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 4.0.2 tag - git checkout v4.0.2
5. Install Ruby dependencies - bundle install
6. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
7. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

NOTE: Node 18 not supported yet. If you run into issues upgrading directly from 3.5.3, checkout v4.0.0 tag and the upgrade to v4.0.2

4.1.0

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch --tags
4. Checkout 4.1.0 tag - git checkout v4.1.0
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Run DB migration - RAILS_ENV=production bundle exec rails db:migrate
8. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
9. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.1

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.1 tag - git checkout v4.1.1
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
8. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.2

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.3 tag - git checkout v4.1.2
5. Update rbenv version - git -C /home/mastodon/.rbenv/plugins/ruby-build pull
6. Install Ruby 3.0.6 - RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.6
7. Install Ruby dependencies - bundle install
8. Install JS dependencies - yarn install
9. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.3

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.3 tag - git checkout v4.1.3
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. (Optional) Upgrade reverse proxy Content-Security-Policy: default-src 'none'; form-action 'none' & X-Content-Type-Options: nosniff. More info can be found in dist/nginx.conf.
8. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.4

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.4 tag - git checkout v4.1.4
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. (Optional) Upgrade reverse proxy Content-Security-Policy: default-src 'none'; form-action 'none' &X-Content-Type-Options: nosniff. More info can be found in dist/nginx.conf.
8. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.5

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.5 tag - git checkout v4.1.5
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.6

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.6 tag - git checkout v4.1.6
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install
7. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.7

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.7 tag - git checkout v4.1.7
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.8

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.8 tag - git checkout v4.1.8
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.1.9

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.9 tag - git checkout v4.1.9
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming

4.2.0

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.1.9 tag - git checkout v4.2.0
5. Update Streaming Server Service
   1. sudo cp ~mastodon/live/dist/mastodon-streaming*.service /etc/systemd/system/
   2. sudo systemctl daemon-reload
6. Update rbenv version - git -C /home/mastodon/.rbenv/plugins/ruby-build pull
7. Install Ruby 3.2.2 - RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.2
8. Install Ruby dependencies - bundle install
9. Install JS dependencies - yarn install --frozen-lockfile
10. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
11. Run predeployment DB migration - SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
12. Restart services - systemctl start mastodon-sidekiq mastodon-web mastodon-streaming
13. Run postdeployment DB migration - RAILS_ENV=production bundle exec rails db:migrate

4.2.1

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.1 tag - git checkout v4.2.1
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile

4.2.2

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.2 tag - git checkout v4.2.2
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile

4.2.3

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.3 tag - git checkout v4.2.3
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile

4.2.4

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.4 tag - git checkout v4.2.4
5. Update rbenv version - git -C /home/mastodon/.rbenv/plugins/ruby-build pull
6. Install Ruby 3.2.3 - RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.3
7. Install Ruby dependencies - bundle install
8. Install JS dependencies - yarn install --frozen-lockfile
9. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile

4.2.5

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.5 tag - git checkout v4.2.5
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.2.6

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.6 tag - git checkout v4.2.6
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.2.7

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.7 tag - git checkout v4.2.7
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.2.8

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.8 tag - git checkout v4.2.8
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.2.9

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.9 tag - git checkout v4.2.9
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.2.10

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.10 tag - git checkout v4.2.10
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.2.11

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.11 tag - git checkout v4.2.11
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile

4.2.12

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.12 tag - git checkout v4.2.12
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile
7. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile

4.2.13

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.2.13 tag - git checkout v4.2.13
5. Install Ruby dependencies - bundle install
6. Install JS dependencies - yarn install --frozen-lockfile

4.3.0 NOT WORKING

1. Stop services - systemctl stop mastodon-*.service
2. Backup database and env file
3. Fetch tags - git fetch && git fetch --tags
4. Checkout 4.3.0 tag - git checkout v4.3.0
5. Install yarn4 - corepack enable then, corepack prepare
6. Install Ruby dependencies - bundle install
7. Install JS dependencies - yarn install --immutable
8. Generate secrets - RAILS_ENV=production bin/rails db:encryption:init
9. Copy secrets to .env.production file
10. Precompile assets - RAILS_ENV=production bundle exec rails assets:precompile
11. Run predeployment database migrations - SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
12. Restart services - sudo systemctl restart mastodon-sidekiq mastodon-streaming mastodon-web
13. Run postdeployment database migrations - RAILS_ENV=production bundle exec rails db:migrate

Restart Services

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

Documentation

• https://docs.joinmastodon.org/admin/troubleshooting/index-corruption
• https://docs.joinmastodon.org/admin/install/
• https://docs.joinmastodon.org/admin/upgrading/
• https://docs.joinmastodon.org/admin/backups/
• https://docs.joinmastodon.org/admin/migrating/
• https://docs.joinmastodon.org/admin/tootctl/