Mastodon Server Tips

I was on the Mastodon server for the last several months, but due to the admin’s personal situation he had to shut down the server, so I decided to try setting up my one single-user instance. (It actually turned out to be a tiny multi-person instance when my friend Mike asked to join.)

(I’m Give me a follow!)

I tried to get everything set up using Docker Compose based on the docker-compose.yml file in the Mastodon repo. It was pretty straightforward, but I ran into a few gotchas, which I figured I’d document here:

  1. The Mastodon services expect the Postgres user to be a member of a group named with the same name. (If your DB user is mastodon, then its group should also be mastodon.
  2. The Mastodon web/API server will silently refuse any non-HTTPS connections. If you’re running a reverse proxy in front of it which terminates the SSL connection, you need to include the X-Forwarded-Proto header. This was really hard to figure out, since the Mastodon server didn’t so much as log the connection attempt.
  3. The Mastodon web/API server will reject any connection not using the hostname it was configured to run under. It does log that it rejected the connection, but not the reason.
  4. You may want your Mastodon handle (eg to use a domain that’s different from the one the server runs on. For instance, my server is at If I had known how, I would have configured my handle to be @json, without the “micro”. You can do this using the LOCAL_DOMAIN and WEB_DOMAIN environment variables. You can find details in the documentation. You can’t change this after you start using your instance!
  5. SendGrid has a free tier if you send less than 100 emails per day. This post on the Mastodon Discourse forums helped me get it set up.

There are definitely a few minor things that don’t seem to work properly, but I’m not sure if it’s either “federation ain’t perfect,” or something that’s my fault, or a problem with the software. For instance, I can’t seem to add a post with video uploaded from my iPhone. Your mileage may vary.

Hope this can help someone! At a minimum, this has been a fun experiment. I definitely wouldn’t recommend administrating a server for a large community though…that sounds like a lot of work both in terms of setting policies and moderation, and also in terms of keeping the services up and running and responding quickly. But stand up a little server for your friends, it might be fun!

Leave a Reply

Your email address will not be published. Required fields are marked *