My notes when upgrading a Mastodon server from 3.5.3 to 4.0.2 which was using the official DigitalOcean droplet.

Not as trivial as I had hoped! Maybe this will be useful to someone else.

Create Snapshot Of Server

First, make a snapshot of your droplet. Backup. Backup backup backup.

In DigitalOcean, browse to your droplet and find Snapshots. Create a new snapshot and name it appropriately so you can find it later. It will take 1-3 minutes per GB of your droplet.

Wait patiently for this to complete.

Update Source Code

Login to the droplet, switch to mastodon user and update the source.

Based on https://github.com/mastodon/mastodon/releases/tag/v4.0.2

su - mastodon

cd /home/mastodon/live

git fetch && git checkout v4.0.2

Upgrade Ruby

Documentation recommend 3.0.4, but I could not get bundle to update my Ruby dependencies on 3.0.3, so I had to upgrade.

Based on https://github.com/mastodon/mastodon/issues/15457

git -C /home/mastodon/.rbenv/plugins/ruby-build pull

rbenv install 3.0.4 --verbose

I recommend running with --verbose as this takes forever and it is good to check what it is up to.

Download More RAM

I had massive issues later on with getting the web service to run. Errors like "Error: Webpacker can't find media/images/preview.png in /home/mastodon/live/public/packs/manifest.json"

To debug the web service not starting properly, I ran journalctl -f -u mastodon-web > log.txt as root, which dumped the (incredibly long) error messages into a file for me to look through. Run this command and then load the web frontend to stream errors into the file. Hit Ctrl+C to exit when done. I used less log.txt to browse the file, use whatever text viewer/editor you are comfortable with.

The issue was that I didn't have enough RAM to run the webpacker when migrating. So before running the next steps, I had to add more RAM using a swapfile.

Skip over this step if you know you have enough, and come back if you get issues later where precompiling assets fails.

Based on https://github.com/mastodon/mastodon/issues/5836

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Update bundle and yarn

Install any dependencies from ruby and web assets.

Based on https://github.com/mastodon/mastodon/releases/tag/v4.0.0

bundle install

yarn install

Run Migration

Run these steps to perform early database migration and precompile the web assets.

Based on https://github.com/mastodon/mastodon/releases/tag/v4.0.0

SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate

RAILS_ENV=production bundle exec rails assets:precompile

Restart Mastodon

Type exit to leave the mastodon user and return to root.

Based on https://docs.joinmastodon.org/admin/upgrading/

systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming

Post Migration

Once the server is running again, run this final post-deployment step to finish migration.

Based on https://github.com/mastodon/mastodon/releases/tag/v4.0.0

su - mastodon

RAILS_ENV=production bundle exec rails db:migrate

Restart Mastodon Again

Type exit to leave the mastodon user and return to root.

Based on https://github.com/mastodon/mastodon/releases/tag/v4.0.0

systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming

Bonus Tips

Debugging Precompile Step

I found that precompiling assets would fail with no error message.

Edit config/webpacker.yml and add this line under production: webpack_compile_output:true

You will now get error messages that can help you diagnose any issues.

Based on https://discourse.joinmastodon.org/t/failing-assets-precompile-without-error-output/2113/7