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
- Log into the Linux based device
- 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.
- 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%> - When prompted, enter an email address and agree to the terms of service
- Choose whether to share your email and receive emails from certbot
- Certbot will output information regarding the location of the certificate files
- 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
- 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 - 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 - Press CTRL+O, Enter, CTRL+X to write the changes to .env
- 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
- 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 - Open a web browser and navigate to https://<%WEB_DOMAIN%>
- Click Sign in then login using the owner email and generated password from earlier
- Select Preferences from the lower right of the user interface
- Select Account from the left navigation menu
- Enter the generated password in the Current password field, then enter and confirm a new password for the current user > Click Save Changes
- Select Logout from the left navigation menu
- Log back in using the owner account email address and updated password
- Welcome to Mastodon