Setting up Mastodon Using Docker and Docker-Compose – Linux Liaison

Setting up Mastodon Using Docker and Docker-Compose

Note: This guide is a work in progress. It is currently mostly complete. If there are any corrections to be made, you can contact me at my new instance here.

Like most projects, this was decided on a whim. I wanted to set up a Mastodon instance for the purpose of learning about the administration and moderation tools that are available to instance owners/moderators. I’d found myself woefully unexperienced when speaking with some admins. I heard about not finding any reports from a given user and I thought some things along the lines of, “how do you search reports?” and “what does a report look like?” Considering I already use Docker, I figured I’d just add this to my Docker stack using docker-compose.

Seeing as the existing documentation is either out of date or the setup script for Mastodon is malformed, I figured I’d write my own guide on how to set up a Mastodon instance using Docker and docker-compose.

This guide assumes that you’re at least a bit familiar with docker-compose. This guide also assumes that you’ve already used the nginx-proxy container image before. If you haven’t please head to the repo for information on how to use it. Let’s jump in.

  1. Decide the parent directory you want to have the Mastodon server files to be hosted in and cd to it from your favourite terminal emulator.
  2. Clone the Mastodon repo: git clone live
  3. cd live to move into the root of the server files
  4. Checkout to the latest stable branch: git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
  5. If you don’t need/want to build the container images, open docker-compose.yml and remove any of the lines with build: .
  6. For use with the nginx-proxy container, add a section to the web service section called environment so that we can add the environment variables required.
  7. In this section add - VIRTUAL_PORT=3000 and - replacing with the domain you’ll be using for your Mastodon instance
  8. Save and close the file
  9. Run cp .env.production.sample .env.production to initialize the configuration
  10. Run docker-compose build to pull the correct images from the Docker Hub
  11. Correct permissions on the public folder by running chown -R 991:991 public. Prepend sudo if necessary
  12. Run docker-compose run --rm web bundle exec rake mastodon:setup to start the setup process. Pulling the container images will probably take a while, depending on your internet connection

This is where I began to have issues. Everything up until this point is pretty solid. The problem with the setup script is that it has to be run twice to actually initialize everything correctly.

  1. Follow all the prompts right until after you’re presented with the lines showing the configuration you’ll be having. Copy that into the .env.production file you created before, right at the top
  2. Save and close the file
  3. Quit the setup process by pressing Ctrl+c and then run docker-compose run --rm web bundle exec rake mastodon:setup again
  4. Enter all the same answers as before, but follow the setup all the way to the end. Take note of the password so you can log into your admin account
  5. If you’ll be using nginx-proxy add your nginx-proxy configuration to the docker-compose.yml file, save, and close the file
  6. Run docker-compose up -d
  7. Visit to log in and set up your instance, replacing the domain with the one you’re using for the instance

If you have any issues with this guide, please send me an email at linuxliaison at fastmail dot com.

Leave a Reply

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.