Skip to content

Install Mastodon in Docker Swarm

Mastodon is an open-source, federated (i.e., decentralized) social network, inspired by Twitter's "microblogging" format, and used by upwards of 4.4M early-adopters, to share links, pictures, video and text.

Mastodon Screenshot

Why would I run my own instance?

That's a good question. After all, there are all sorts of public instances available, with a range of themes and communities. You may want to run your own instance because you like the tech, because you just think it's cool

You may also have realized that since Mastodon is federated, users on your instance can follow, toot, and interact with users on any other instance!

If you're not into that much effort / pain, you're welcome to join our instance

Mastodon requirements


Already deployed:


  • DNS entry for your epic new social network, pointed to your keepalived IP
  • An S3-compatible bucket for serving media (I use Backblaze B2)
  • An SMTP gateway for delivering email notifications (I use Mailgun)
  • A business card, with the title "I'm CEO, Bitch"

Setup data locations

First, we create a directory to hold the Mastodon docker-compose configuration:

mkdir /var/data/config/mastodon

Then we setup directories to hold all the various data:

mkdir -p /var/data/runtime/mastodon/redis
mkdir -p /var/data/runtime/mastodon/elasticsearch
mkdir -p /var/data/runtime/mastodon/postgres 

Why /var/data/runtime/mastodon and not just /var/data/mastodon?

The data won't be able to be backed up by a regular filesystem backup, because it'll be in use. We still need to store it somewhere though, so we use /var/data/runtime, which is excluded from automated backups. See Data Layout for details.

Setup Mastodon environment

Create /var/data/config/mastodon/mastodon.env something like the example below..

# This is a sample configuration file. You can generate your configuration
# with the `rake mastodon:setup` interactive setup wizard, but to customize
# your setup even further, you'll need to edit it manually. This sample does
# not demonstrate all available configuration options. Please look at
# for the full documentation.

# Note that this file accepts slightly different syntax depending on whether
# you are using `docker-compose` or not. In particular, if you use
# `docker-compose`, the value of each declared variable will be taken verbatim,
# including surrounding quotes.
# See:

# Federation
# ----------
# This identifies your server and cannot be changed safely later
# ----------  # (1)!

# Redis
# -----

# PostgreSQL
# ----------
DB_PASS=tootmeupbuttercup # (2)!

# Elasticsearch (optional)
# ------------------------
ES_ENABLED=false  # (3)!
# Authentication for ES (optional)

# Secrets
# -------
# Make sure to use `rake secret` to generate secrets
# -------
SECRET_KEY_BASE=imafreaksecretbaby  # (4)!

# Web Push
# --------
# Generate with `rake mastodon:webpush:generate_vapid_key`
# docker run -it tootsuite/mastodon bundle exec rake mastodon:webpush:generate_vapid_key
# --------

# Sending mail # (6)!
# ------------

# File storage (optional)  # (7)!
# -----------------------

# IP and session retention
# -----------------------
# Make sure to modify the scheduling of ip_cleanup_scheduler in config/sidekiq.yml
# to be less than daily if you lower IP_RETENTION_PERIOD below two days (172800).
# -----------------------
  1. Set this to the FQDN you plan to use for your instance.
  2. It doesn't matter what this is set to, since we're using POSTGRES_HOST_AUTH_METHOD=trust, but I've left it in for completeness and consistency with Mastodon's docs
  3. Only enable this if you have enough resources for an Elasticsearch instance for full-text indexing
  4. Generate these with docker run -it tootsuite/mastodon bundle exec rake secret
  5. Generate these with docker run -it tootsuite/mastodon bundle exec rake mastodon:webpush:generate_vapid_key
  6. You'll need to complete this if you want to send email
  7. You'll need to complete this if you want to host media elsewhere

Mastodon Docker Swarm config

Create a docker swarm config file in docker-compose syntax (v3), something like the example below.. example:

Fast-track with premix! πŸš€

I automatically and instantly share (with my sponsors) a private "premix" git repository, which includes necessary docker-compose and env files for all published recipes. This means that sponsors can launch any recipe with just a git pull and a docker stack deploy πŸ‘.

πŸš€ Update: Premix now includes an ansible playbook, so that sponsors can deploy an entire stack + recipes, with a single ansible command! (more here)

version: '3.5'
    image: postgres:14-alpine
      - internal
      test: ['CMD', 'pg_isready', '-U', 'postgres']
      - /var/data/runtime/mastodon/postgres:/var/lib/postgresql/data    

    image: redis:6-alpine
      - internal
      test: ['CMD', 'redis-cli', 'ping']
      - /var/data/runtime/mastodon/redis:/data

  # es:
  #   image:
  #   environment:
  #     - "ES_JAVA_OPTS=-Xms512m -Xmx512m -Des.enforce.bootstrap.checks=true"
  #     - "xpack.license.self_generated.type=basic"
  #     - ""
  #     - "xpack.watcher.enabled=false"
  #     - "xpack.graph.enabled=false"
  #     - ""
  #     - "bootstrap.memory_lock=true"
  #     - ""
  #     - "discovery.type=single-node"
  #     - "thread_pool.write.queue_size=1000"
  #   networks:
  #      - internal
  #   healthcheck:
  #      test: ["CMD-SHELL", "curl --silent --fail localhost:9200/_cluster/health || exit 1"]
  #   volumes:
  #      - /var/data/runtime/mastodon/elasticsearch:/usr/share/elasticsearch/data
  #   ulimits:
  #     memlock:
  #       soft: -1
  #       hard: -1
  #     nofile:
  #       soft: 65536
  #       hard: 65536
  #   ports:
  #     - '9200:9200'

    image: tootsuite/mastodon
    env_file: /var/data/config/mastodon/mastodon.env
    command: bash -c "rm -f /mastodon/tmp/pids/; bundle exec rails s -p 3000"
      - internal
      - traefik_public
      test: ['CMD-SHELL', 'wget -q --spider --proxy=off localhost:3000/health || exit 1']
      - /var/data/mastodon:/mastodon/public/system
        # traefik
        - traefik.enable=true

        # traefikv2
        - "traefik.http.routers.mastodon.rule=Host(``)"
        - "traefik.http.routers.mastodon.entrypoints=https"
        - ""

    image: tootsuite/mastodon
    env_file: /var/data/config/mastodon/mastodon.env
    command: node ./streaming
      - internal
      - traefik_public
      test: ['CMD-SHELL', 'wget -q --spider --proxy=off localhost:4000/api/v1/streaming/health || exit 1']
        # traefik
        - traefik.enable=true

        # traefikv2
        - "traefik.http.routers.mastodon.rule=Host(``) && PathPrefix(`/api/v1/streaming`))"
        - "traefik.http.routers.mastodon.entrypoints=https"
        - ""

    image: tootsuite/mastodon
    env_file: /var/data/config/mastodon/mastodon.env
    command: bundle exec sidekiq
      - internal
      - /var/data/mastodon:/mastodon/public/system
      test: ['CMD-SHELL', "ps aux | grep '[s]idekiq\ 6' || false"]

  ## Uncomment to enable federation with tor instances along with adding the following ENV variables
  ## http_proxy=http://privoxy:8118
  # tor:
  #   image: sirboops/tor
  #   networks:
  #      - internal
  # privoxy:
  #   image: sirboops/privoxy
  #   volumes:
  #     - /var/data/mastodon/privoxy:/opt/config
  #   networks:
  #     - internal

    external: true
    driver: overlay
        - subnet:


Setup unique static subnets for every stack you deploy. This avoids IP/gateway conflicts which can otherwise occur when you're creating/removing stacks a lot. See my list here.


Unlike most recipes, we can't just deploy Mastodon into Docker Swarm, and trust it to setup its database itself. We have to "pre-warm" it using docker-compose, per the official docs (Docker Swarm is not officially supported)

Start with docker-compose

From the /var/data/config/mastodon directory, run the following to start up the Mastodon environment using docker-compose. This will result in a broken environment, since the database isn't configured yet, but it provides us the opportunity to configure it.

docker-compose -f mastodon.yml up -d

The output should look something like this:

root@raphael:/var/data/config/mastodon# docker-compose -f mastodon.yml up -d
WARNING: Some services (streaming, web) use the 'deploy' key, which will be ignored. Compose does not support 'deploy' configuration - use `docker stack deploy` to deploy to a swarm.
WARNING: The Docker Engine you're using is running in swarm mode.

Compose does not use swarm mode to deploy services to multiple nodes in a swarm. All containers will be scheduled on the current node.

To deploy your application across the swarm, use `docker stack deploy`.

Creating mastodon_sidekiq_1   ... done
Creating mastodon_db_1        ... done
Creating mastodon_redis_1     ... done
Creating mastodon_streaming_1 ... done
Creating mastodon_web_1       ... done

Create database

Run the following to create the database. You can expect this to take a few minutes, and produce a lot of output:

cd /var/data/config/mastodon
docker-compose -f mastodon.yml run --rm web bundle exec rake db:migrate

Create admin user

Next, decide on your chosen username, and create your admin user:

cd /var/data/config/mastodon
docker-compose -f mastodon.yml run --rm web bin/tootctl accounts \
create <username> --email <email address> --confirmed --role admin

The password will be output on completion1:

root@raphael:/var/data/config/mastodon# docker-compose -f mastodon.yml run --rm web bin/tootctl accounts create batman --email --confirmed --role admin
WARNING: Some services (streaming, web) use the 'deploy' key, which will be ignored. Compose does not support 'deploy' configuration - use `docker stack deploy` to deploy to a swarm.
New password: c6eb8e0d10cd6f0aa874b7a384177a08

Turn off docker-compose

We've setup the essestials now, everything else can be configured either via the UI or via the .env file, so tear down the docker-compose environment with:

docker-compose -f mastodon.yml down

The output should look like this:

root@raphael:/var/data/config/mastodon# docker-compose -f mastodon.yml down
WARNING: Some services (streaming, web) use the 'deploy' key, which will be ignored. Compose does not support 'deploy' configuration - use `docker stack deploy` to deploy to a swarm.
Stopping mastodon_streaming_1 ... done
Stopping mastodon_web_1       ... done
Stopping mastodon_db_1        ... done
Stopping mastodon_redis_1     ... done
Stopping mastodon_sidekiq_1   ... done
Removing mastodon_streaming_1 ... done
Removing mastodon_web_1       ... done
Removing mastodon_db_1        ... done
Removing mastodon_redis_1     ... done
Removing mastodon_sidekiq_1   ... done
Removing network mastodon_internal
Network traefik_public is external, skipping

Launch Mastodon!

Launch the Mastodon stack by running:

docker stack deploy mastodon -c /var/data/config/mastodon/mastodon.yml

Now hit the URL you defined in your config, and you should see your beautiful new Mastodon instance! Login with your configured credentials, navigate to Preferences, and have fun tweaking and tooting away!

Once you're done, "toot" me by mentioning in a toot! πŸ‘‹


If your instance feels lonely, try using some relays to bring in the federated firehose!


What have we achieved? Even though we had to jump through some extra hoops to setup database and users, we now have a fully-swarmed Mastodon instance, ready to federate with the world!



  • Mastodon configured, running, and ready to toot!

Chef's notes πŸ““

  1. Or, you can just reset your password from the UI, assuming you have SMTP working ↩

Tip your waiter (sponsor) πŸ‘

Did you receive excellent service? Want to compliment the chef? (..and support development of current and future recipes!) Sponsor me on Github / Ko-Fi / Patreon, or see the contribute page for more (free or paid) ways to say thank you! πŸ‘

Employ your chef (engage) 🀝

Is this too much of a geeky PITA? Do you just want results, stat? I do this for a living - I'm a full-time Kubernetes contractor, providing consulting and engineering expertise to businesses needing short-term, short-notice support in the cloud-native space, including AWS/Azure/GKE, Kubernetes, CI/CD and automation.

Learn more about working with me here.

Flirt with waiter (subscribe) πŸ’Œ

Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the RSS feed, or leave your email address below, and we'll keep you updated.

Your comments? πŸ’¬