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 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 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:
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
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 example.com
This will obtain the certificate, and save it in the directory
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
/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_key, updating the path with the correct domain name.
Reload nginx for the changes to take effect:
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
In the docs step Installing Ruby you were instructed to add a new user
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.