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