How to set up a Mastodon server in Docker

With the sale of Twitter, a lot of people have been looking for alternatives and backup options. Due to humanity finally seeming to have gotten sick of the primary problems with the centralized model, they’re going back to decentralized social networks.

Mastodon is one of these.

Although not new, it’s definitely a good alternative, being developed roughly around the same time as Twitter, with many of the same naming schemes and concepts.

Setting up your own can seem a bit challenging at first, as I’ve noticed the documentation not really mentioning the docker setup, and the manual way being somewhat involved.

After some messing around, I’ve figured it out and set it up within my usual webserver stack. If you’re curious how the stack I’m running it on is setup, you can find a blog explaining it in more detail here

Without further ado, here’s how to set up your own (assuming you’ve already installed docker and docker-compose and git):

(Updated quick version for everyone else 06-11-2022):

1) curl/wget https://raw.githubusercontent.com/mastodon/mastodon/main/docker-compose.yml to a location of choice on your server.

2) Adjust the docker-compose file to your liking.

  • Make sure to put the storage volumes somewhere you can back them up, or leave them as is to have them created in subdirectories next to the docker-compose file.

  • Make sure to also remember the ports you end up setting for the mappings. The Web container is the one that needs to be available from outside, having its port 3000 either mapped to the outside, or proxied through nginx (recommended for security reasons).

  • If you want to go through NginX, you can change the ‘ports’ section to ‘expose’, this will just open the ports on the container, and you can access the container by IP or name from nginx on the host itself.

3) docker-compose run --rm web bundle exec rake mastodon:setup. This will guide you through creating a .env.production file appropriate for your installation. Note down the data it gives you carefully, as you’ll need it later. The .env.production file should be saved outside the container properly if you’ve set up your volumes correctly.

4) run docker-compose -d to start the containers, and then docker-compose logs -f to keep an eye on the logs and see if everything goes well.

5) If all goes well, it should be up and running!

Dragonhive/Dergnz stack version

1) git clone https://github.com/mastodon/mastodon.git. This pulls the full repository local, including the docker-compose files and .env.production files and other things it references. Do note this is technically more than we need, as we just need the docker-compose file and generate an appropriate .env.production file, but for the sake of convenience I’m just going to clone the whole repo here.

2) Adjust the docker-compose.yml file to your liking. Put the volumes somewhere you can back them up. Make sure your network is defined, so it can actually connect to your frontend webserver.

In the case of the dragonhive stack, change the bottom lines so it looks something like this:

networks:   
  external_network:
    external:   
      name: frontendweb
  internal_network:
    internal: true

and change the ports mappings to expose, and remove the 127.0.0.1:3000: part so you just have a single number left. This will open the firewall port to the container, so the frontend container can access it.

3) docker-compose run --rm web bundle exec rake mastodon:setup. This will guide you through creating a .env.production file appropriate for your installation. Note down the data it gives you carefully, as you’ll need it later. The .env.production file should be saved inside the container properly if you’ve set up your volumes correctly.

4) Add the following config parameters to .env.production if you’re using the dergnz stack with jwilder’s nginx proxy:

VIRTUAL_HOST="mastodon.your.domain"
LETSENCRYPT_HOST="mastodon.your.domain"
VIRTUAL_PORT='3000'
VIRTUAL_PROTO=http

5) run docker-compose -d, and then docker-compose logs -f to keep an eye on the logs and see if everything goes well.

6) if all went well, your Mastodon instance should be up and running at the domain your specified in the config above. If you have a custom webserver stack, make sure you either port forward or nginx forward to the container or host’s port, depending on how you configured it. The web container is the one the internet should be connecting to, the default port is 3000.

F.A.Q

  • Q: After migration, I can’t log in, and I’m seeing weird database errors in the docker logs, but the website does seem to be visible to the public

  • A: Try running docker compose run --rm web rails db:migrate, this should make sure the database is has all features and settings set correctly.

  • Q: I don’t want to use docker-compose, can I just use docker?
  • A: There’s a dockerfile in the main repo that you can also try, I haven’t used it yet though.

Updated: