View source for Editing Mastodon Docker Deployment Guide 260402

= Mastodon on Docker — Self-Hosted Deployment Guide =

'''Behind Nginx Proxy Manager with Let's Encrypt SSL'''

Using linuxserver.io image | Ubuntu 24 | Docker Compose

{{Tip|This guide is written so that a thinking model AI agent (such as one running on your local server via Ollama/Open WebUI) can follow these instructions step-by-step and get Mastodon running without human intervention. Every command is verified against a successful real-world deployment. Verify all outputs at each stage before proceeding.}}

== Why Mastodon Is More Complex Than Other Docker Apps ==

Most Docker apps are a single process that sits behind a reverse proxy. Mastodon is different in three important ways:

# It runs '''five processes simultaneously''' inside one container: Rails (web), Puma (app server), Sidekiq (background jobs), a Node.js streaming server, and its own internal nginx. This is managed by s6-overlay.
# It assumes it owns ports 80 and 443 directly. Placing it behind NPM requires overriding its internal nginx SSL behavior, which it resists.
# It enforces cryptographic secrets before it will even start. Unlike most apps, Mastodon refuses to boot without SECRET_KEY_BASE, OTP_SECRET, VAPID keys, and ACTIVE_RECORD_ENCRYPTION keys all pre-generated.

{{Warning|Mastodon also takes 30-60 seconds to fully boot. Always check logs before assuming something is wrong.}}

== Prerequisites ==

* Ubuntu 24 server (bare metal or VM)
* Docker and Docker Compose installed
* Nginx Proxy Manager (NPM) already running on ports 80 and 443
* A domain name with an A record pointing to your server's public IP
* Gmail account with an App Password generated (for SMTP)

{{Critical|To generate a Gmail App Password: go to myaccount.google.com/apppasswords, create a new app password, and save it in a password manager immediately. Do not paste it into any chat or shared document.}}

== Step 1 — Create the Directory ==

All Mastodon files live in one directory. Create it and navigate into it:

<syntaxhighlight lang="bash">
mkdir -p /opt/mastodon
cd /opt/mastodon
</syntaxhighlight>

The volume mount <code>/opt/mastodon/config:/config</code> will be auto-created by linuxserver on first run and will populate with nginx config, keys, and logs.

== Step 2 — Generate All Secrets Before Starting ==

{{Warning|The linuxserver image entrypoint interferes with rails commands. Always override with <code>--entrypoint=""</code> and use the full path <code>/app/www/bin/rails</code>. You must also set the working directory with <code>-w /app/www</code> for rake tasks.}}

=== SECRET_KEY_BASE (run once) ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" lscr.io/linuxserver/mastodon:latest /app/www/bin/rails secret
</syntaxhighlight>

=== OTP_SECRET (run again for a different value) ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" lscr.io/linuxserver/mastodon:latest /app/www/bin/rails secret
</syntaxhighlight>

=== VAPID Keys ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" -w /app/www lscr.io/linuxserver/mastodon:latest /app/www/bin/rails mastodon:webpush:generate_vapid_key
</syntaxhighlight>

Output will look like:

<syntaxhighlight lang="text">
VAPID_PRIVATE_KEY=OqZ07QTRwoO...
VAPID_PUBLIC_KEY=BA7IhTSGcf0...
</syntaxhighlight>

=== ACTIVE_RECORD_ENCRYPTION Keys (new requirement in Mastodon 4.3+) ===

<syntaxhighlight lang="bash">
docker run --rm --entrypoint="" -w /app/www lscr.io/linuxserver/mastodon:latest /app/www/bin/rails db:encryption:init
</syntaxhighlight>

Output will look like:

<syntaxhighlight lang="text">
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=Xf3Rvl...
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=TK5DQU...
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=f8cyBe...
</syntaxhighlight>

{{Critical|Copy all seven values now. You will not be able to change them after the database is initialized without risking data loss.}}

== Step 3 — Create docker-compose.yml ==

Create the file:

<syntaxhighlight lang="bash">
nano /opt/mastodon/docker-compose.yml
</syntaxhighlight>

Paste the following, replacing all placeholder values with your actual secrets and domain:

<syntaxhighlight lang="yaml">
services:
  mastodon:
    image: lscr.io/linuxserver/mastodon:latest
    container_name: mastodon
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Manila
      - LOCAL_DOMAIN=toot.yourdomain.com
      - NO_SSL=true
      - FORCE_SSL=false
      - TRUSTED_PROXY_IP=127.0.0.1/8,::1/128,192.168.0.0/16
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - DB_HOST=db
      - DB_USER=mastodon
      - DB_NAME=mastodon_production
      - DB_PASS=your_db_password
      - DB_PORT=5432
      - ES_ENABLED=false
      - SECRET_KEY_BASE=<from step 2>
      - OTP_SECRET=<from step 2>
      - VAPID_PRIVATE_KEY=<from step 2>
      - VAPID_PUBLIC_KEY=<from step 2>
      - ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=<from step 2>
      - ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=<from step 2>
      - ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=<from step 2>
      - SMTP_SERVER=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_LOGIN=your_gmail@gmail.com
      - SMTP_PASSWORD=your_gmail_app_password
      - SMTP_FROM_ADDRESS=notifications@yourdomain.com
      - SMTP_AUTH_METHOD=plain
      - SMTP_OPENSSL_VERIFY_MODE=peer
      - S3_ENABLED=false
    volumes:
      - /opt/mastodon/config:/config
    ports:
      - 8667:80
    networks:
      - mastodon-net
    depends_on:
      - db
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: mastodon-redis
    volumes:
      - /opt/mastodon/redis:/data
    networks:
      - mastodon-net
    restart: unless-stopped

  db:
    image: postgres:14-alpine
    container_name: mastodon-db
    environment:
      - POSTGRES_DB=mastodon_production
      - POSTGRES_USER=mastodon
      - POSTGRES_PASSWORD=your_db_password
    volumes:
      - /opt/mastodon/postgres:/var/lib/postgresql/data
    networks:
      - mastodon-net
    restart: unless-stopped

networks:
  mastodon-net:
    driver: bridge
</syntaxhighlight>

{{Note|Port 8667:80 maps host port 8667 to the container's internal port 80. This avoids conflict with NPM which already owns ports 80 and 443. Choose any unused host port.}}

== Step 4 — Start the Stack ==

<syntaxhighlight lang="bash">
cd /opt/mastodon
docker compose up -d
</syntaxhighlight>

Watch the logs and wait for the boot sequence to complete (30-60 seconds):

<syntaxhighlight lang="bash">
docker compose logs -f mastodon
</syntaxhighlight>

A successful boot ends with lines like:

<syntaxhighlight lang="text">
Connection to localhost (127.0.0.1) 3000 port [tcp/*] succeeded!
[ls.io-init] done.
Sidekiq 8.x connecting to Redis with options...
</syntaxhighlight>

{{Warning|Do not proceed until you see <code>[ls.io-init] done</code>. Mastodon takes 30-60 seconds to fully initialize on first boot. The ACTIVE_RECORD_ENCRYPTION crash loop means those keys are missing or not being read from the compose file.}}

== Step 5 — Fix Internal nginx SSL Conflict ==

The linuxserver image generates an nginx config that listens on both port 80 and port 443, and passes <code>X-Forwarded-Proto: http</code> to Rails. This causes Rails to issue a 301 redirect to HTTPS even when NO_SSL=true and FORCE_SSL=false are set. The fix is to edit the nginx config directly and hardcode X-Forwarded-Proto to https.

{{Warning|This must be done after first boot because the config files are generated on first run into <code>/opt/mastodon/config/nginx/</code>. You must edit both the active .conf and the .conf.sample so changes survive container restarts.}}

=== Remove 443 listeners and hardcode X-Forwarded-Proto ===

<syntaxhighlight lang="bash">
# Fix active config
docker exec mastodon sed -i 's/listen 443 ssl default_server;//g' /config/nginx/site-confs/default.conf
docker exec mastodon sed -i 's/listen \[\:\:\]:443 ssl default_server;//g' /config/nginx/site-confs/default.conf
docker exec mastodon sed -i 's/include \/config\/nginx\/ssl.conf;//g' /config/nginx/site-confs/default.conf
docker exec mastodon sed -i 's/proxy_set_header X-Forwarded-Proto $scheme;/proxy_set_header X-Forwarded-Proto https;/g' /config/nginx/site-confs/default.conf

# Fix sample so it survives restarts
docker exec mastodon sed -i 's/listen 443 ssl default_server;//g' /config/nginx/site-confs/default.conf.sample
docker exec mastodon sed -i 's/listen \[\:\:\]:443 ssl default_server;//g' /config/nginx/site-confs/default.conf.sample
docker exec mastodon sed -i 's/include \/config\/nginx\/ssl.conf;//g' /config/nginx/site-confs/default.conf.sample
docker exec mastodon sed -i 's/proxy_set_header X-Forwarded-Proto $scheme;/proxy_set_header X-Forwarded-Proto https;/g' /config/nginx/site-confs/default.conf.sample

# Reload nginx without restarting the container
docker exec mastodon s6-svc -r /run/service/svc-nginx
</syntaxhighlight>

=== Verify the fix ===

<syntaxhighlight lang="bash">
curl -v http://localhost:8667 -H "Host: toot.yourdomain.com"
</syntaxhighlight>

You should see <code>HTTP/1.1 200 OK</code>. If you still see <code>301 Moved Permanently</code>, check that the sed commands ran correctly:

<syntaxhighlight lang="bash">
docker exec mastodon cat /config/nginx/site-confs/default.conf | grep -n "301\|https\|ssl\|443"
</syntaxhighlight>

== Step 6 — Configure Nginx Proxy Manager ==

In NPM, create a new Proxy Host with these settings:

{| class="wikitable"
! Setting !! Value
|-
| Domain Name || toot.yourdomain.com
|-
| Scheme || http
|-
| Forward Hostname / IP || Your server's LAN IP (e.g. 192.168.1.100)
|-
| Forward Port || 8667 (or whichever host port you chose)
|-
| Cache Assets || Off
|-
| Block Common Exploits || On
|-
| Websockets Support || On (critical for live feed)
|-
| SSL Certificate || Request via Let's Encrypt
|-
| Force SSL || On
|-
| HTTP/2 Support || On
|-
| HSTS Enabled || Off (optional, enable after confirming working)
|}

{{Warning|Websockets Support must be On. Mastodon uses WebSockets for the live timeline feed. Without it the interface loads but does not update in real time.}}

{{Note|The domain must already have a DNS A record pointing to your public IP before requesting a Let's Encrypt certificate. Verify with: <code>curl -s https://dns.google/resolve?name=toot.yourdomain.com | grep data</code>}}

== Step 7 — Create Admin Account ==

Mastodon starts with zero accounts. Create your owner account from the command line:

<syntaxhighlight lang="bash">
docker exec -it mastodon /app/www/bin/tootctl accounts create YOUR_USERNAME --email YOUR@EMAIL --confirmed --role Owner
</syntaxhighlight>

The command outputs a randomly generated password. Copy it immediately. Log in at <code>https://toot.yourdomain.com</code> with your email and that password.

{{Warning|After logging in you will see a 'pending review' banner even on your own account. This is because registrations require admin approval. Approve yourself with:}}

<syntaxhighlight lang="bash">
docker exec -it mastodon /app/www/bin/tootctl accounts approve YOUR_USERNAME
</syntaxhighlight>

Then change your password immediately in Settings > Account > Account Settings.

== Problems Encountered and Countermeasures ==

{| class="wikitable"
! Problem !! Cause !! Fix
|-
| Crash loop: ACTIVE_RECORD_ENCRYPTION keys missing || New requirement in Mastodon 4.3+. Container exits immediately without these three keys set. || Generate with: <code>docker run --rm --entrypoint="" -w /app/www lscr.io/... /app/www/bin/rails db:encryption:init</code>
|-
| Redis: connect ECONNREFUSED 127.0.0.1:6379 || Redis service not in same compose file, or containers not on same Docker network. || Add redis service to same docker-compose.yml with a shared named network (mastodon-net).
|-
| bin/rails: no such file or directory || linuxserver entrypoint intercepts the command before rails runs. || Always use <code>--entrypoint=""</code> and full path: <code>/app/www/bin/rails</code>
|-
| No Rakefile found error for rake tasks || Working directory not set; rake cannot find the app root. || Add <code>-w /app/www</code> to the docker run command.
|-
| 301 redirect loop at toot.yourdomain.com || Internal nginx passes X-Forwarded-Proto: http to Rails. Rails sees HTTP and redirects to HTTPS infinitely. || Sed-edit both default.conf and default.conf.sample to hardcode X-Forwarded-Proto https. Reload nginx with s6-svc.
|-
| NO_SSL=true and FORCE_SSL=false not working || FORCE_SSL was removed in newer Mastodon. NO_SSL prevents regenerating the config but cannot fix an already-generated config. || Edit the nginx config files directly. The sample must also be edited or changes are overwritten on restart.
|-
| 403 Forbidden on curl test || Host header mismatch. Mastodon's nginx rejects requests where the Host header does not match LOCAL_DOMAIN. || Always test with: <code>curl -v http://localhost:8667 -H "Host: toot.yourdomain.com"</code>
|-
| Pending review banner after login || Mastodon requires admin approval for all accounts including ones created via tootctl. || Run: <code>docker exec -it mastodon /app/www/bin/tootctl accounts approve YOUR_USERNAME</code>
|-
| Port 80/443 already in use || NPM is already running on those ports on the host. || Map Mastodon to an unused host port (e.g. 8667:80). NPM proxies to it. Drop the 443 mapping entirely.
|-
| Container still starting when testing || Mastodon takes 30-60 seconds to fully boot. curl or browser tests fail during this window. || Watch logs: <code>docker compose logs -f mastodon</code>. Only test after seeing [ls.io-init] done.
|}

== Instructions for AI Agent Execution ==

If you are an AI agent following this guide, use this decision tree at each stage:

=== At each step, verify before proceeding ===

# Run the command exactly as written.
# Check the output against the expected output described.
# If the output does not match, consult the Problems table above before retrying.
# Never proceed to the next step if the current step has not produced the expected output.

=== Key verification commands ===

<syntaxhighlight lang="bash">
# Is the container running?
docker compose ps

# Is it fully booted?
docker compose logs mastodon | tail -20
# Look for: [ls.io-init] done.

# Is nginx listening on port 80 inside the container?
docker exec mastodon netstat -tlnp
# Look for: 0.0.0.0:80 LISTEN nginx

# Is Mastodon responding correctly?
curl -v http://localhost:8667 -H "Host: toot.yourdomain.com"
# Look for: HTTP/1.1 200 OK
# A 301 means the nginx X-Forwarded-Proto fix has not been applied yet.

# Are all env vars present?
docker exec mastodon env | grep -E 'ACTIVE_RECORD|SECRET|VAPID|NO_SSL|FORCE'
# All seven secrets must appear with non-empty values.

# What ports are in use on the host?
docker ps --format "table {{.Names}}\t{{.Ports}}"
</syntaxhighlight>

{{Tip|If the container is crash-looping, you cannot exec into it. Use <code>docker run --rm --entrypoint=""</code> to run one-off commands against the image instead.}}

== Post-Setup Checklist ==

* [ ] Change your admin password in Settings > Account > Account Settings
* [ ] Enable Two-Factor Authentication in Settings > Account > Two-Factor Auth
* [ ] Set up server rules and description in Admin > Server Settings
* [ ] Close registrations or set to invite-only in Admin > Server Settings > Registrations
* [ ] Revoke any SMTP credentials exposed during setup and generate new ones
* [ ] Back up /opt/mastodon/config and /opt/mastodon/postgres regularly
* [ ] Back up your docker-compose.yml and store it in Forgejo or another version-controlled location

{{Critical|The ACTIVE_RECORD_ENCRYPTION keys and all secrets in docker-compose.yml are the most critical backup. If these are lost and the database is intact, recovery is extremely difficult.}}

[[Category:Open Source]]
[[Category:Tutorials]]
[[Category:Docker]]
[[Category:Self-Hosting]]
[[Category:System Administration]]