How to Deploy Mastodon with Docker Compose: A Step-by-Step Guide

X (Twitter) Facebook Pinterest LinkedIn

Mastodon has surged in popularity as an open-source, federated social networking platform. It allows users to host their own servers, or “instances,” and communicate seamlessly across the Mastodon network. For those interested in deploying their own Mastodon instance, Docker and Docker Compose offer a streamlined way to get up and running. This article will guide you through setting up Mastodon using Docker Compose, making it accessible for both beginners and experienced users.

Table of Contents

Prerequisites

Before diving into the deployment process, ensure you have the following prerequisites met:

Docker installed on your server
Docker Compose installed
A domain name pointing to your server (for SSL configuration)

Step 1: Create a Docker Compose File

The first step is to create a docker-compose.yml file which defines the services needed for Mastodon. This file will include the web service, sidekiq service, and a Postgres database.

version: '3'
services:
  db:
    image: postgres:12-alpine
    environment:
      - POSTGRES_USER=mastodon
      - POSTGRES_PASSWORD=securepassword
      - POSTGRES_DB=mastodon_production
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - internal_network

  redis:
    image: redis:6-alpine
    networks:
      - internal_network

  web:
    image: tootsuite/mastodon
    command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -p 3000 -b '0.0.0.0'"
    volumes:
      - ./public/system:/mastodon/public/system
    environment:
      - REDIS_HOST=redis
      - DB_HOST=db
      - DB_USER=mastodon
      - DB_NAME=mastodon_production
      - DB_PASS=securepassword
      - RAILS_SERVE_STATIC_FILES=true
      - RAILS_ENV=production
    ports:
      - "3000:3000"
    depends_on:
      - db
      - redis
    networks:
      - external_network
      - internal_network

  sidekiq:
    image: tootsuite/mastodon
    command: bundle exec sidekiq -q default -q mailers -q pull -q push
    environment:
      - REDIS_HOST=redis
      - DB_HOST=db
      - DB_USER=mastodon
      - DB_NAME=mastodon_production
      - DB_PASS=securepassword
      - RAILS_ENV=production
    depends_on:
      - db
      - redis
    networks:
      - internal_network

networks:
  external_network:
    external: true
  internal_network:
    internal: true

Replace securepassword with a strong, secure password of your choosing.

Step 2: Setup Environment Variables

Mastodon requires a .env.production file for environment variables. Create this file in the same directory as your docker-compose.yml and configure the necessary variables, such as:

DB_HOST=db
DB_USER=mastodon
DB_NAME=mastodon_production
DB_PASS=securepassword
REDIS_HOST=redis
SECRET_KEY_BASE=generate_this_with_rake
OTP_SECRET=generate_this_with_rake

You can generate SECRET_KEY_BASE and OTP_SECRET values by running docker-compose run --rm web rake secret.

Step 3: Initialize the Database

Once you have your environment configured, initialize the database with:

docker-compose run --rm web rails db:migrate
docker-compose run --rm web rails assets:precompile

Step 4: Launch Mastodon

With the configuration and initial setup complete, you can start your Mastodon instance by running:

docker-compose up -d

This command launches all the services defined in your docker-compose.yml file in detached mode.

Step 5: Finalizing Setup

After starting Mastodon, finalize your instance setup by accessing your domain in a web browser and following the on-screen instructions to create an admin account and configure your instance.

Conclusion

Deploying Mastodon with Docker and Docker Compose simplifies the process, making it accessible for administrators of any experience level. Following the steps outlined in this guide, you’ll have a Mastodon instance up and running quickly. Remember to keep your instance updated and secure by regularly applying Mastodon updates and monitoring your Docker containers.

Author
Recent Posts

Follow me

Anastasios Antoniadis

Anastasios Antoniadis is the founder and editor-in-chief of BORDERPOLAR... He is a software engineer, blogger, and avid gamer covering tech, gaming, and coding guides for over 4 years. He is a 2014 graduate of the Department of Informatics and Telecommunications of the University of Athens, an M.Sc. holder in Computer Science, and a Ph.D. student in Program Analysis.