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.