Sunny Garden Hub

Notes On Installing Mastodon From Source

These notes are from my personal experience. I’ve followed these steps multiple times successfully, but no guarantees.

At the time of writing this post, there are some known issues with the official installation instructions which these notes attempt to address.

The docs, and these notes, assume a completely fresh install of Ubuntu 20.04 or Debian 11 and you should definitely use one of these for the most pain free experience.

I have personally tested these steps on Ubuntu 20.04, Ubuntu 22.04, and Debian 11

Minimum Requirements


Things To Do Differently From The Docs

Skip The Firewall Instructions

Use ufw instead, it’s much simpler.

apt install ufw

These rules rate limit 22 (SSH), and allow 80 (HTTP) and 443 (HTTPS):

ufw limit 22
ufw allow 80
ufw allow 443

Turn ufw on:

ufw enable

If you want to make changes to ufw later, these are pretty good docs:

Installing Ruby

The recommended ruby version for Mastodon v4.0.x is 3.0.4 up from 3.0.3 in the docs.

This step takes a while, add the --verbose option so you can see what’s happening.

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.4 --verbose
rbenv global 3.0.4

Setting up nginx and SSL

You will encounter errors following the doc sections Setting up nginx and Acquiring a SSL certificate as written, follow these steps in order instead:

Acquiring a SSL certificate

We’ll use Let’s Encrypt to get a free SSL certificate:

certbot certonly --nginx -d

This will obtain the certificate, and save it in the directory /etc/letsencrypt/live/

Setting up nginx

Copy the configuration template for nginx from the Mastodon directory:

cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon

Then edit /etc/nginx/sites-available/mastodon to replace with your own domain name, and make any other adjustments you might need.

Un-comment the lines starting with ssl_certificate and ssl_certificate_key, updating the path with the correct domain name.

Reload nginx for the changes to take effect:

Test nginx

At this point you should be able to visit your domain in the browser and see the elephant hitting the computer screen error page. This is because we haven’t started the Mastodon process yet.

If you instead see the error 502 Bad Gateway and nginx logging errors such as:

[crit] 33163#33163: *45 stat() "/home/mastodon/live/public/favicon.ico" failed (13: Permission denied), client: x.x.x.x, server:, request: "GET /favicon.ico HTTP/2.0"`

You may need to fix permissions…

Fix Permissions on /home/mastodon

In the docs step Installing Ruby you were instructed to add a new user mastodon.

Depending on your distribution and version, you may need to fix the permissions on the /home/mastodon directory so that nginx can read the files it needs to serve.

I have only had to do this on Ubuntu 22.04.

ll /home
drwxr-x---  8 mastodon mastodon 4096 Nov 19 05:06 mastodon/

chmod o+rx /home/mastodon

ll /home
drwxr-xr-x  8 mastodon mastodon 4096 Nov 19 05:06 mastodon/

After fixing these permissions, the “elephant hitting the computer screen” error page displayed as expected.

Good To Go

Finish up the rest of the installation and configuration instructions.