Run Mastodon - A Federated Twitter Alternative - in Docker 🌱

What is Mastodon?

Mastodon is a free, open-source social network server based on ActivityPub where users can follow friends and discover new ones. On Mastodon, users can publish anything they want: links, pictures, text, video. All Mastodon servers are interoperable as a federated network (users on one server can seamlessly communicate with users from another one, including non-Mastodon software that implements ActivityPub)! -https://github.com/mastodon/mastodon

Installing Docker

  1. Log into the Linux based device
  2. Run the following commands in the terminal
    # install prerequisites
    sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg-agent -y
    # add docker gpg key
    curl -fsSL https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)/gpg | sudo apt-key add -
    # add docker software repository
    sudo add-apt-repository "deb [arch=$(dpkg --print-architecture)] https://download.docker.com/linux/$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release) $(lsb_release -cs) stable"
    # install docker
    sudo apt install docker-ce docker-compose containerd.io -y
    # enable and start docker service
    sudo systemctl enable docker && sudo systemctl start docker
    # add the current user to the docker group
    sudo usermod -aG docker $USER
    # reauthenticate for the new group membership to take effect
    su - $USER

Generating SSL Certificate with Let's Encrypt

NOTE: In order for Let's Encrypt to verify ownership of the DNS name, the host certbot is running from must be accessible via port 80 (http) or port 443 (https). For homelab users, this will normally involve port forwarding from the router to the certbot host, which is beyond the scope of this tutorial. Just note, I have forwarded port 80 on my router to the host running certbot for this handshake to complete successfully.

  1. Continue with the following commands in a terminal window
    # remove apt version of certbot if installed
    sudo apt remove certbot -y
    # install snapd
    sudo apt install snapd -y
    # install snap core and update
    sudo snap install core; sudo snap refresh core
    # install certbot snap
    sudo snap install --classic certbot
    # create certbot symbolic link
    sudo ln -s /snap/bin/certbot /usr/bin/certbot
    # if a web server process is currently using port 80, stop it before proceeding
    # generate a certificate
    sudo certbot certonly --standalone --preferred-challenges http -d <%DNS NAME%>
  2. When prompted, enter an email address and agree to the terms of service
  3. Choose whether to share your email and receive emails from certbot
  4. Certbot will output information regarding the location of the certificate files
  5. Continue with the following commands in a terminal window
    # create ssl-certs group
    sudo groupadd ssl-certs
    # add $USER and root users to group
    sudo usermod -aG ssl-certs $USER
    sudo usermod -aG ssl-certs root
    # verify the members of ssl-cert
    getent group ssl-certs
    # set owner group of /etc/letsencrypt
    sudo chgrp -R ssl-certs /etc/letsencrypt
    # set permissions on /etc/letsencrypt
    sudo chmod -R g=rX /etc/letsencrypt

Running the Mastodon Container Stack

  1. Now that Docker is installed, run the following commands to setup the Mastodon Docker containers
    # create working directories
    mkdir ~/docker/postgres -p && mkdir ~/docker/redis -p && mkdir ~/docker/mastodon/public/system -p && mkdir ~/docker/nginx/conf -p
    # pull the mastodon web container
    docker pull tootsuite/mastodon
    # generate secrets, run this 2 times
    docker run --rm -it tootsuite/mastodon bundle exec rake secret
    # generate VAPID keys
    docker run --rm -it tootsuite/mastodon bundle exec rake mastodon:webpush:generate_vapid_key
    # create a mastodon .env file
    # copy the generated secrets and keys into the .env file
    # make sure to set the LOCAL_DOMAIN as this cannot be changed later
    nano ~/docker/mastodon/.env
  2. Paste the following into the .env file, then edit the LOCAL_DOMAIN, WEB_DOMAIN, PostgreSQL, Secrets, Web Push and SMTP settings
    NOTE: A full example .env file can be find at https://github.com/mastodon/mastodon/blob/main/.env.production.sample

    # 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
    # https://docs.joinmastodon.org/admin/config/ 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: https://github.com/mastodon/mastodon/issues/16895

    # Federation
    # ----------
    # This identifies your server and cannot be changed safely later
    # ----------
    LOCAL_DOMAIN=i12bretro.local

    # ----------
    # Optional, if different than LOCAL_DOMAIN
    # ----------
    #WEB_DOMAIN=toots.webredirect.org

    # Redis
    # -----
    REDIS_HOST=redis
    REDIS_PORT=6379

    # PostgreSQL
    # ----------
    DB_HOST=postgres
    DB_USER=mastodon_rw
    DB_NAME=mastodon
    DB_PASS=Ma5toD0n!
    DB_PORT=5432

    # Secrets
    # -------
    # Make sure to use `rake secret` to generate secrets
    # -------
    SECRET_KEY_BASE=
    OTP_SECRET=

    # Web Push
    # --------
    # Generate with `rake mastodon:webpush:generate_vapid_key`
    # --------
    VAPID_PRIVATE_KEY=
    VAPID_PUBLIC_KEY=

    # Sending mail
    # ------------
    SMTP_SERVER=smtp.example.com
    SMTP_PORT=25
    SMTP_LOGIN=
    SMTP_PASSWORD=
    SMTP_FROM_ADDRESS=mastodon@example.com


    # 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).
    # -----------------------
    IP_RETENTION_PERIOD=31556952
    SESSION_RETENTION_PERIOD=31556952

  3. Press CTRL+O, Enter, CTRL+X to write the changes to .env
  4. Continue with the following steps in the terminal
    # set owner of docker directory
    sudo chown "$USER":"$USER" ~/docker -R
    # create containers
    docker network create containers
    # run the postgesql container
    docker run -d --name postgres -e POSTGRES_USER=mastodon_rw -e POSTGRES_PASSWORD=Ma5toD0n! -e POSTGRES_DB=mastodon -v ~/docker/postgres:/var/lib/postgresql/data --network containers --restart=unless-stopped postgres:latest
    # run the redis container
    docker run -d --name redis -v ~/docker/redis:/data --network containers --restart=unless-stopped redis
    # initialize the mastodon database
    docker run --rm -it --network containers --env-file ~/docker/mastodon/.env tootsuite/mastodon rails db:migrate
    # run the mastodon frontend container
    docker run -d --name mastodon --env-file ~/docker/mastodon/.env -p 3000:3000 -v ~/docker/mastodon/public/system:/mastodon/public/system --network containers --restart=unless-stopped tootsuite/mastodon bash -c "rm -f /mastodon/tmp/pids/server.pid; bundle exec rails s -p 3000"
    # connect to shell inside mastodon container
    docker exec -it mastodon /bin/bash
    # set the RAILS_ENV variable
    RAILS_ENV=production
    # create an owner/admin account
    # copy the password output for later
    bin/tootctl accounts create <%username%> --email <%email address%> --confirmed --role Owner
    # exit the container
    exit
    # run the mastodon streaming container
    docker run -d --name mastodon-stream --env-file ~/docker/mastodon/.env -p 4000:4000 --network containers --restart=unless-stopped tootsuite/mastodon node ./streaming
    # run the mastodon sidekiq container
    docker run -d --name mastodon-sidekiq --env-file ~/docker/mastodon/.env --network containers -v ~/docker/mastodon/public/system:/mastodon/public/system --restart=unless-stopped tootsuite/mastodon bundle exec sidekiq

Setting Up the Nginx Proxy Server

  1. Now that all the pieces of Mastodon are running, we'll configure an nginx proxy server
    # download the default mastodon nginx configuration
    wget -O ~/docker/nginx/conf/mastodon.conf https://raw.githubusercontent.com/mastodon/mastodon/main/dist/nginx.conf
    # replace some options to work running in docker containers
    sed -i "s/try_files \$uri =404;/try_files \$uri @proxy;/" ~/docker/nginx/conf/mastodon.conf
    # update the server_name with the URL being used to reach mastodon
    # make sure to replace WEB_DOMAIN
    sed -i "s/server_name example.com;/\server_name <%WEB_DOMAIN%>;/" ~/docker/nginx/conf/mastodon.conf
    # update mastodon frontend server
    sed -i 's/server 127.0.0.1:3000/server mastodon:3000/' ~/docker/nginx/conf/mastodon.conf
    # update mastodon stream server
    sed -i 's/server 127.0.0.1:4000/server mastodon-stream:4000/' ~/docker/nginx/conf/mastodon.conf
    # update the ssl certificate path
    # make sure to replace DNS NAME
    sed -i 's/# ssl_certificate\s*\/etc\/letsencrypt\/live\/example.com\/fullchain.pem;/ssl_certificate\t\/etc\/letsencrypt\/live\/<%DNS NAME%>\/fullchain.pem;/' ~/docker/nginx/conf/mastodon.conf
    # update the ssl key path
    # make sure to replace DNS NAME
    sed -i 's/# ssl_certificate_key\s*\/etc\/letsencrypt\/live\/example.com\/privkey.pem;/ssl_certificate_key\t\/etc\/letsencrypt\/live\/<%DNS NAME%>\/privkey.pem;/' ~/docker/nginx/conf/mastodon.conf
    # create nginx proxy container
    docker run --name nginx -p 80:80 -p 443:443 --network containers -v ~/docker/nginx/conf:/etc/nginx/conf.d:ro -v /etc/letsencrypt:/etc/letsencrypt:ro -d nginx
  2. Open a web browser and navigate to https://<%WEB_DOMAIN%>
  3. Click Sign in then login using the owner email and generated password from earlier
  4. Select Preferences from the lower right of the user interface
  5. Select Account from the left navigation menu
  6. Enter the generated password in the Current password field, then enter and confirm a new password for the current user > Click Save Changes
  7. Select Logout from the left navigation menu
  8. Log back in using the owner account email address and updated password
  9. Welcome to Mastodon