Skip to content

Instantly share code, notes, and snippets.

@ShadowJonathan
Forked from weex/mastodon-docker-setup.md
Last active July 3, 2025 12:05
Show Gist options
  • Save ShadowJonathan/dda087e410f6b24006e4992d112bd076 to your computer and use it in GitHub Desktop.
Save ShadowJonathan/dda087e410f6b24006e4992d112bd076 to your computer and use it in GitHub Desktop.
Mastodon Docker Setup

Mastodon Docker Setup

Setting up

Clone Mastodon's repository.

# Clone Mastodon to ~/mastodon directory
git clone https://github.com/mastodon/mastodon
# Change directory to ~/mastodon
cd ~/mastodon

Review the settings in docker-compose.yml.

Getting the Mastodon image

Installing Docker containers

If you're not making any local code changes or customizations on your instance, you can use a prebuilt Docker image to avoid the time and resource consumption of a build.

  1. Open docker-compose.yml in your favorite text editor.
  2. Add environment variables to the db section:
    environment:
        POSTGRES_PASSWORD: xyz <-- choose a safe one, 20-30 chars
        POSTGRES_DB: mastodon_production
        POSTGRES_USER: mastodon
        POSTGRES_HOST_AUTH_METHOD: trust
  3. To use pre-built images comment out the build: . lines for the web, streaming, and sidekiq services.
  4. Save the file and exit the text editor.
  5. Run docker-compose build to either pull or build the necessary container images.
  6. Create the public/system dir with mkdir public/system
  7. Set correct file-owner with sudo chown -R 991:991 public/system

Configuration

First, make sure .env.production exists, even if empty, to satisfy docker;

  • touch .env.production

Next generate a configuration with:

docker-compose run --rm web bundle exec rake mastodon:setup

This is an interactive wizard that will guide you through the options and generate app secrets.

  1. Enter the Fully Qualified Domain Name (FQDN) of your Mastodon instance.
  2. Select if you want a Single User instance (not recommended, but if you prefer, use that).
  3. Obviously, you are running Mastodon in a docker instance, so type Y (or hit return, as it's the default)
  4. The PostgreSQL host is db, the port is 5432 (again, default), the database is mastodon_production, the database user is mastodon and the password is the one you chose and put into docker-compose.yml.
  5. The redis server is redis, the port is 6379 and the password is empty.
  6. If you want to store uploaded files on the cloud, enter Y here and put in the necessary data.
  7. If you want to send emails from the local machine, enter Y. I chose N and was able to send email via a free mailgun account. Accept the default port then enter the user and password for the email sending account. Select the SMTP authentication type plain and none for OpenSSL verify mode. Choose what sender address the emails will have. mastodon@*yourdomain.com* is a decent possibility.

Now it will output your configuration. Copy and paste that into the .env.production file.

The wizard will setup the database schema and precompile assets. After it's done, you can launch Mastodon with:

docker-compose up -d

Reverse Proxy

You need a reverse proxy in front of your Mastodon instance.

Caddy configuration

Use the following caddy configuration;

domain.com {
        root * /home/<user>/mastodon/public # the same ./public as in the docker compose, replace <user>

        encode gzip

        @static file
        handle @static {
                file_server
        }

        handle /api/v1/streaming* {
                reverse_proxy localhost:4000 # the "streaming" container in the docker compose
        }

        handle {
                reverse_proxy localhost:3000 # the "web" container in the docker compose
        }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment