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.
- Decide the parent directory you want to have the Mastodon server files to be hosted in and
cdto it from your favourite terminal emulator.
- Clone the Mastodon repo:
git clone https://github.com/tootsuite/mastodon.git live
cd liveto move into the root of the server files
- Checkout to the latest stable branch:
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
- If you don’t need/want to build the container images, open
docker-compose.ymland remove any of the lines with
- For use with the
nginx-proxycontainer, add a section to the web service section called
environmentso that we can add the environment variables required.
- In this section add
example.comwith the domain you’ll be using for your Mastodon instance
- Save and close the file
cp .env.production.sample .env.productionto initialize the configuration
docker-compose buildto pull the correct images from the Docker Hub
- Correct permissions on the
publicfolder by running
chown -R 991:991 public. Prepend
docker-compose run --rm web bundle exec rake mastodon:setupto 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.
- 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.productionfile you created before, right at the top
- Save and close the file
- Quit the setup process by pressing
Ctrl+cand then run
docker-compose run --rm web bundle exec rake mastodon:setupagain
- 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
- If you’ll be using
nginx-proxyconfiguration to the
docker-compose.ymlfile, save, and close the file
docker-compose up -d
example.comto 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.