How to upgrade Mastodon to v4.1.0 🐘

sean

(Edit: An updated upgrade guide is available at: HOWTO upgrade Mastodon to v4.2.5 running on Ruby 3.2)

Mastodon v4.1.0 was recently released!There are many enhancements and fixes, includeing new poll options and (finally!) a listing of your followed hashtags. 🎉

If you've installed Mastodon on Opalstack via our installer and want to upgrade to v4.1.0 then the procedure below will get you there. If you're running any other version of Mastodon, upgrading to any other version other than 4.1.0, or are running a manual installation then this procedure is not for you. We'll have a generic upgrade procedure available in the future.

Note that the commands below use the following placeholders which you'll need to substitute as follows:

app_name - the name of your Mastodon application. Your app names are available at: https://my.opalstack.com/apps/
db_user - the name of your database user, available in: ~/apps/app_name/mastodon/.env.production
db_name - the name of your database, available in: ~/apps/app_name/mastodon/.env.production

To proceed:

Run the following commands to make a backup (if you're on a VPS make sure you have sufficient space first by running "df -h /" on the server):

pg_dump -U db_user -f ~/apps/app_name/db.sql db_name
cp -Rp ~/apps/app_name ~/app_name_backup

Run the following command to disable your cron jobs:

crontab -l | sed -e 's/^/# /g' | crontab

Note: this will disable all of your cron jobs for your shell user. If you have cron jobs unrelated to your Mastodon app and you don't want them disabled then run crontab -e to edit your cron jobs manually.

Run the following commands to perform the upgrade.

Note that the app will be offline during the upgrade due to the memory constraints of your hosting plan. If you're certain you have a lot of spare RAM (for example if you are on a 4GB VPS or higher with at least 2GB of free RAM) and don't want the site to be offline then you can omit the ../stop command at your own risk.

cd ~/apps/app_name/
./stop
source setenv
wget https://nodejs.org/dist/v16.18.1/node-v16.18.1-linux-x64.tar.xz
tar xf node-v16.18.1-linux-x64.tar.xz 
mv node-v16.18.1-linux-x64 node
export PATH=$PWD/node/bin:$PATH
corepack enable
yarn set version classic
cd mastodon
git checkout -- .
git fetch && git checkout v4.1.0
ln -f -s ../lib/node_modules/corepack/dist/yarn.js bin/yarn
bundle config set jobs 4
bundle install
RAILS_ENV=production bundle exec rails db:migrate
RAILS_ENV=production bundle exec rails assets:precompile
../restart

Run the following command to re-enable your cron jobs (or run crontab -e to edit your cron jobs manually):

crontab -l |  sed -e 's/^# //g' | crontab

Your backup will very likely use a lot of disk space. To remove it following the upgrade, run the following command:

rm -rf ~/app_name_backup

You're done!

mergy

Thanks for the instructions for newbie Mastodon instance admins like me!

All went well. I did add one thing prior to doing the backups - I took the files storage down to just 2 days to cut the amount of data an files because I typically run like 7 days, doubling that for backup gets me close to my service level limits.

cd ~/apps/<appname>/mastodon/
source ../setenv
RAILS_ENV=production bundle exec tootctl statuses remove --days 2;
RAILS_ENV=production bundle exec tootctl media remove --days 2;
RAILS_ENV=production bundle exec tootctl preview_cards remove --days 2

This got me down to like 40gb or so - so doing the backup still left me with enough space. Thanks again for the help and assistance through all this! Been fun running my own server on Opalstack.

brianrlawson

Hey @sean - as you know, I'm a noob and have trouble with my install in the past. So, before I started rolling I wanted to pause and ask...is it safe to perform these same steps to go to 4.1.1?

Thanks,
Brian

sean

brianrlawson yes, just change this line:

git fetch && git checkout v4.1.0

... to this:

git fetch && git checkout v4.1.1

Also, if you've used the above upgrade procedure to move to 4.1.0 in the past then you can skip most of the first half of it, eg like so:

cd ~/apps/app_name/
./stop
source setenv
cd mastodon
git checkout -- .
git fetch && git checkout v4.1.1
bundle config set jobs 4
bundle install
yarn install
RAILS_ENV=production bundle exec rails assets:precompile
../restart

brianrlawson

sean Hey all - checking in once again because I'm paranoid about screwing something up. I know that 4.1.2 is now released and I assume that I could follow the same 4.1.1 steps. However, I spotted that the Mastodon release notes specifically mention a recommended Ruby version update to 3.0.6. My Mastodon Admin Dashboard reports Ruby 3.0.2p107. Is that something I need to take care of during the upgrade steps, or is that a back-end infrastructure thing that will just happen behind the scenes for me?

Thanks,
Brian

nick

brianrlawson Backup your entire app first, but this should technically start your Mastodon instance using Ruby 3.0.6 (just update all the USER and APPNAME variables) but it doesn't really change the version it was built with:

Log in to SSH as your app's shell user.
Execute the following commands:

cd ~
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bash_profile

Log out of SSH and then log back in, then run the following commands:

mkdir -p ~/tmp && export TMPDIR=~/tmp
scl enable devtoolset-10 -- rbenv install 3.0.6
echo "3.0.6" > /home/USER/apps/APPNAME/mastodon/.ruby-version

Edit ~/apps/APPNAME/supervisord.conf to replace /opt/rh/rh-ruby30/root/usr/local/bin:/opt/rh/rh-ruby30/root/usr/bin which should be on the PATH= line (ie line 12) with /home/USER/.rbenv/shims:/home/USER/.rbenv/bin
Run the following commands to do a full stop/start:

~/apps/APPNAME/stop
pkill -f supervisor
~/apps/APPNAME/start

You may need to try ~/apps/APPNAME/restart if the app is not loading for whatever reason. But if there are any issues please open a support ticket.

mergy

nick this working well for me. I did have to make a minor tweak on

git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

git clone https://github.com/rbenv/ruby-build.git /home/<USER>/.rbenv/plugins/ruby-build

and that did the trick.

mergy

Referencing this post now for current update. Taking the media down to 1 day this time though.

danjewett

mergy I think you have an extra ")" in your replacement command.
/home/<USER>/.rbenv)"/plugins/ruby-build

Used your tweak though and it worked really well. Thanks!

mergy

going to create a new post for v4.1.4 issue - got there but Yarn error.

mergy

danjewett Fixed! thank you

mergy

Let's see now if this works for 4.2.0 - will see later today.

sean

mergy Don't forget to make those backups!

mergy

taking it down to 1 day of media for a decent-sized backup

db122

Anyone bump to 4.2.0 (now 4.2.1) using these techniques? I just upgraded to 4.1.10 no problem but I guess 4.2 is a big step forward with new minimum dependency versions.

sean

db122 I've reviewed the upgrade steps (ie this and this) and the procedure hasn't changed.

The steps to go to 4.2.1 from a 4.1.x release are:

cd ~/apps/app_name/
./stop
source setenv
cd mastodon
git checkout -- .
git fetch && git checkout v4.2.1
bundle config set jobs 4
bundle install
yarn install --frozen-lockfile
RAILS_ENV=production bundle exec rails assets:precompile
../restart

db122

OK, gave this a shot (upgrading from 4.1.10 to 4.2.1) and received a couple of errors. I'd be grateful for advice but not a burning issue for me right now.

Warning: the running version of Bundler (2.2.22) is older than the version that created the lockfile (2.4.13). We suggest you to upgrade to the version that created the lockfile by runninggem install bundler:2.4.13.

I was successful in running that command but it didn't seem to affect the version of bundle in the path.

Later, I received these errors:
bundler: failed to load command: rails (/home/user/apps/m/mastodon/vendor/bundle/ruby/3.0.0/bin/rails) /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:302:incheck_for_activated_spec!': You have already activated uri 0.10.1, but your Gemfile requires uri 0.12.2. Since uri is a default gem, you can either remove your dependency on it or try updating to a newer version of bundler that supports uri as a default gem. (Gem::LoadError)
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:31:in block in setup' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/spec_set.rb:159:ineach'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/spec_set.rb:159:in each' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:26:inmap'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:26:in setup' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler.rb:149:insetup'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/setup.rb:10:in block in <top (required)>' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/ui/shell.rb:136:inwith_level'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/ui/shell.rb:88:in silence' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/setup.rb:10:in<top (required)>'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli/exec.rb:61:in require_relative' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli/exec.rb:61:inkernel_load'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli/exec.rb:28:in run' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli.rb:474:inexec'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor/command.rb:27:in run' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor/invocation.rb:127:ininvoke_command'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor.rb:392:in dispatch' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli.rb:30:indispatch'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor/base.rb:485:in start' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli.rb:24:instart'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/libexec/bundle:49:in block in <top (required)>' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/friendly_errors.rb:128:inwith_friendly_errors'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/libexec/bundle:37:in <top (required)>' from /opt/rh/rh-ruby30/root/usr/bin/bundle:23:inload'
from /opt/rh/rh-ruby30/root/usr/bin/bundle:23:in <main>' bundler: failed to load command: rails (/home/user/apps/m/mastodon/vendor/bundle/ruby/3.0.0/bin/rails) /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:302:incheck_for_activated_spec!': You have already activated uri 0.10.1, but your Gemfile requires uri 0.12.2. Since uri is a default gem, you can either remove your dependency on it or try updating to a newer version of bundler that supports uri as a default gem. (Gem::LoadError)
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:31:in block in setup' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/spec_set.rb:159:ineach'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/spec_set.rb:159:in each' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:26:inmap'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/runtime.rb:26:in setup' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler.rb:149:insetup'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/setup.rb:10:in block in <top (required)>' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/ui/shell.rb:136:inwith_level'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/ui/shell.rb:88:in silence' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/setup.rb:10:in<top (required)>'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli/exec.rb:61:in require_relative' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli/exec.rb:61:inkernel_load'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli/exec.rb:28:in run' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli.rb:474:inexec'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor/command.rb:27:in run' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor/invocation.rb:127:ininvoke_command'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor.rb:392:in dispatch' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli.rb:30:indispatch'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/vendor/thor/lib/thor/base.rb:485:in start' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/cli.rb:24:instart'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/libexec/bundle:49:in block in <top (required)>' from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/lib/bundler/friendly_errors.rb:128:inwith_friendly_errors'
from /opt/rh/rh-ruby30/root/usr/share/gems/gems/bundler-2.2.22/libexec/bundle:37:in <top (required)>' from /opt/rh/rh-ruby30/root/usr/bin/bundle:23:inload'
from /opt/rh/rh-ruby30/root/usr/bin/bundle:23:in <main>'

nick

db122

Check which version of bunlder you are using to make sure it's the right one.

which bundle

If that doesn't return the correct version (2.4.13), then locate the updated binary executable path with gem environment and look for the EXECUTABLE DIRECTORY line. Then add that to your PATH, ie, to your .bashrc or .bash_profile and restart your SSH session and see if that helps. Eg.

export PATH="/path-to-executable-directory:$PATH"

If you need further assistance, please feel free to open a support ticket and include any extra details that may assist us in troubleshooting the issue.

db122

nick Thanks, that sent me down the right path. Or some path, anyways. 🙂 Server's upgraded to 4.2.1.

mergy

Trying nick script now while I wait for support. Let's see!