2 min read

Tips and troubleshooting for self-hosting Mastodon

Banner image with mastodon character and logo

I've been running a mastodon instance for a little while now (https://toot.sh). I've come across quite a few issues which have caused me a reasonable amount of pain, so I thought I'd document some of them here.

As a general note, the mastodon docs seem to assume you'll use a raw install on the server, despite providing a docker-compose.yml file. Because of this it'll be worth considering your choice of installation carefully. So far I've not had any issues using a container based approach, although I can't say it won't happen in the future. If you do go with the docker-compose install, be aware that various commands (`tootctl` and rails commands in particlular) in the docs will need to be run inside the web container. You can do this by prefixing the command with the docker-compose run command. For example:

docker-compose run --rm web tootctl feeds build

Mastodon docs assume a raw install

The mastodon repo provides a docker-compose file but none of the documentation assumes you'll run the instance this way. Think twice before you go down this path, I've not had any issues caused by using containers themselves but it does mean you need to modify your commands on the regular.

Don't use Cloudflare Minification

Mastodon inserts integrity checks of the html, css, and js content. As a result it's not compatible with any kind of CDN/Reverse proxy doing it. If you're using cloudflare, make sure to turn off Auto Minify in the Speed -> Optimizations page.

If you don't do this, you could unexpectedly end up in a situation where your pages have broken styles, or none at all. For me this happened after a few weeks of everything running just fine, so it's not a problem exclusively for new-installs.

Empty timeline after a restore / re-install / migration

Users timelines are stored in Redis, as such any loss of Redis data means this will need rebulding. You can do this with the tootctl feeds build command.

# For non-docker based installs
tootctl feeds build

# For docker-compose installs
docker-compose run --rm web bin/tootctl feeds build

This command will rebuild all users feeds, if you have a lot of users this could take a while to run. There are various options available to tweak the concurrency.

Elasticsearch complains about storage space

I'm not entirely sure why, as I haven't dug into it deeply, but Elasticsearch may require more storage space than your OS will allow it by default. This requires a change on the host OS rather than the container so proceed with caution.

To test the change you can run sysctl -w vm.max_map_count=262144 (this may require sudo). Then you can restart the container. To make  that persist add the line vm.max_map_count=262144 at the bottom of the /etc/sysctl.conf file. This will be read at boot time so if you do elect to do this, you're probably best off running the command and then adding it into the sysctl.conf file. This change may impact other systems although as I say I've not dug into much yet so you may wish to check it out yourself.