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 https://docs.joinmastodon.org/admin/install/ 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

RAM

• Minimum 4GB or certain steps may fail, such as ruby compile, or asset precompile
• You can probably get away with 2GB of RAM and 2-4GB of swap to pass the compile steps, if you only plan on hosting a handful of users
• Add swap anyway, just in case, these are good instructions: https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-20-04

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: https://www.digitalocean.com/community/tutorials/ufw-essentials-common-firewall-rules-and-commands

Installing Ruby

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.6 --verbose
rbenv global 3.0.6

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 example.com

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

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 example.com 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: example.com, 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.