Skip to content

Latest commit

 

History

History
907 lines (649 loc) · 32.2 KB

Secureish-Mastodon-Setup.md

File metadata and controls

907 lines (649 loc) · 32.2 KB
Raw

Secure-ish Mastodon Setup In A Box

Last Updated: April 22nd, 2018.

Step 1. Create a new VPS

Initial Server Creation

For the purposes of this guide, I'm doing this guide via assuming that you are setting up a Vultr instance.

When logging into Vultr, navigate to Servers and then click the (+) button to set up a new VPS. For the following, I have these as my settings, but yours may vary:

  • Server Location: New York (NJ)
  • Server Type: Ubuntu 16.04 x64 (18.04 when it comes out)
  • Server Size: 2GB memory (or more)
  • Additional Features: Enable IPv6, Enable Auto Backups, Block Storage Compatible

(If you want to choose another location, don't worry about it there not being an option for Block Storage Compatible - it's only if your VPS runs out of SSD space and you need to add more.)

If you do not have an SSH key, I recommend generating an Ed25519 key by doing the following in Linux, Mac OS X or Windows Subsystem for Linux:

$ ssh-keygen -t ed25519

Afterwards, add a new SSH key, paste the contents of id_ed25519.pub to Vultr, and then select that as your SSH Key. Keep id_ed25519 to yourself and never give it out!

Your server hostname should be the domain name of the Mastodon instance you're creating. The server label can be anything (e.g.: mastodon).

It'll take around 3-5 minutes for the initial server setup to complete. When it does, click on the server you've just created, and make note of the root password. Go to "Settings" and make note of the IPv4 Address and the IPv6 Address.

Add your domain via DNS

Navigate to Servers, then DNS, and click "Add Domain" to add your domain. Make note of the IP address of your new instance.

You will be asked to enter in your domain name and IP address. Enter those, submit, and then you'll be at the Manage DNS Domain page.

Make a new IPv6 record by choosing "AAAA" under "Type", pasting the IPv6 address under "Data", and then hitting the + button under "Actions" to add a new one.

Make a new "CNAME" record as well by choosing CNAME, putting a star "*" under "Name", and under Data, type in your domain name e.g. yourdomain.com

With your domain registrar, add in the nameservers that are displayed under NS in the domain records. It may take awhile to propagate (up to 24-48 hours), but it depends on the DNS server you're using.

Step 2. Set up the Server

Setting up a privileged account

Use SSH to connect to your new server by typing in the following command:

$ ssh root@yourdomain.com

Next, add a user that you will use to log in to SSH that is not the root user by adding another user (e.g. privacc, but can be something else):

# adduser privacc

Add sudo privileges:

# usermod -aG sudo privacc

Copy your SSH keys to the privacc account and make them owned by privacc:

# cp -R ~/.ssh $(eval echo "~privacc") && chown -R privacc:privacc $(eval echo "~privacc")/.ssh

Then exit by typing exit. Now try SSHing into your new account:

$ ssh privacc@yourdomain.com

Disable the root account

Now that we're logged in, we can disable password authentication to the root account.

$ sudo nano /etc/ssh/sshd_config

Find the following and replace it with this:

RSAAuthentication yes -> RSAAuthentication no

PasswordAuthentication yes -> PasswordAuthentication no

PermitRootLogin yes -> PermitRootLogin no

Restart our SSH server:

$ sudo systemctl restart sshd

Enable the firewall and update

Add OpenSSH to our firewall and start it:

$ sudo ufw allow OpenSSH
$ sudo ufw enable

Update our servers:

$ sudo apt update
$ sudo apt -y upgrade
$ sudo apt -y dist-upgrade
$ sudo apt -y autoremove

Install ntp (for up to date time):

$ sudo apt install -y ntp

Finally, install fail2ban:

$ sudo apt install -y fail2ban

Set up Docker and Docker Compose

Next, we're going to be setting up Docker and Docker Compose. Docker is a container software that allows us to run software easily from "images", and Docker Compose formats things for us in a way that would run Docker commands without being unnecessarily complicated.

Firstly, run:

$ sudo curl -fsSL https://get.docker.com | bash -E --

Next, we're going to install the latest version of Docker Compose by running these commands:

$ sudo curl -sS "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep 'tag_name' | cut -d\" -f4)/docker-compose-`uname -s`-`uname -m`" > /usr/local/bin/docker-compose
$ sudo chmod a+x /usr/local/bin/docker-compose

When we run this command, we should get versions that match (and the version could be higher):

privacc@yourdomain:~$ echo $COMPOSE_VERSION
1.20.1
privacc@yourdomain:~$ docker-compose --version
docker-compose version 1.20.1, build 5d8c71b

Set up a normal user for Mastodon and give them Docker privileges

For all intents and purposes, where we're running Mastodon should not have sudo privileges, but should be able to run Docker and Docker Compose commands. So for this, we will add a Mastodon user, e.g.:

$ sudo useradd mastodon

Add Docker privileges to the mastodon user:

$ sudo usermod -aG docker mastodon

Finally, we are going to allow port 80 (HTTP) and port 443 (HTTPS) traffic, but we have no firewall rules installed yet that we can point to. As a result, we are going to manually add TCP ports 80 and 443 to our firewall, like so:

$ sudo ufw allow 80/tcp
$ sudo ufw allow 443/tcp

Step 3. Set up Let's Encrypt certificates

We have a few options for encrypting our web server. The original is usually by using Certbot, but I generally like Acme.sh for the fact that it's lightweight, doesn't require root, and can generate ECDSA certificates (which we'll get into in a bit). For this example, we'll be installing Acme.sh.

The first step is to log in to our mastodon account like so:

$ sudo su - mastodon

Once that's done, we can download Acme.sh and install like so:

mastodon@yourdomain:~ $ curl -sS https://raw.githubusercontent.com/Neilpang/acme.sh/master/acme.sh | INSTALLONLINE=1 sh

Our main problem here is that we don't have a web server to confirm that we're really who we are, so we have two options on how we can solve this:

  1. We can create a temporary web-server in our Nginx container, or
  2. We can use Vultr API to verify us via DNS.

We can also set up our skeleton files:

$ mkdir -p .docker/nginx
$ mkdir -p .docker/mastodon
$ touch .docker/mastodon/.env.production
$ mkdir public

Why is Acme.sh not running in a container? We need some way of rebooting Nginx whenever Acme.sh fetches new certificates automatically, and there is no present way to do this if Acme is running isolated from everything else. This might be a little more risky, but this is the only software that you're installing out of Docker (if you choose option 1).

Acme.sh can verify that you own the domain by setting DNS records. However, there is no way for Acme.sh itself to set DNS records via the Vultr API, so we're going to have to grant it access by a program named Lexicon.

The first step is to exit out of our mastodon user back into our privacc user. Next, we're going to have to install Pip, a package manager for the system-installed Python 3, and a few dependencies to support Pip, like so:

$ sudo apt install -y python3-pip build-essential libssl-dev libffi-dev python3-dev

Come back to the mastodon user like so:

$ sudo su - mastodon

Install Lexicon with extras:

$ pip install setuptools wheel dns-lexicon

Verify that Lexicon works:

$ ./.local/bin/lexicon --version

Now, go back to the Vultr Control Panel. Navigate to Account, then API. Copy the Personal Access Token to somewhere safe for now, and add your VPS to Access Control on both IPv4 and IPv6.

So, let's say your VPS's IPv4 is 207.148.123.123. Your VPS's IPv6 is 2001:19f0:...etc. Add your IPv4 address under Access Control and in the field to the right of the slash (/), enter in 32. Add the IPv4. Do the same for IPv6, except for instead of 32, enter in 128. Click Add. This whitelists our VPS to contact Vultr via Lexicon via Acme.sh.

Back in our handy dandy SSH terminal, run the following (replacing inserttokenhere with the token you copied):

$ export PATH="$PATH:$(pwd)/.local/bin"
$ export PROVIDER=vultr
$ export LEXICON_VULTR_TOKEN=inserttokenhere
$ acme.sh --issue -d yourdomain.com -d mail.yourdomain.com --dns dns_lexicon --keylength ec-384

Note: Later in the guide, we're going to be setting up a mailserver as a part of this. If you plan on using SendGrid, Mailgun, or an external SMTP, just leave out -d mail.yourdomain.com.

After about 4 minutes, everything should be verified by Vultr.

Why ec-384? RSA certificates are increasingly vulnerable to being compromised, which is the default. As we're going for a secure install, issuing certificates under ECDSA secp384r1 means that we have the equivalent of a RSA 3072-bit key.

Finally, let's generate pem files for use in Nginx, and tell Acme.sh to restart Nginx each time a certificate renewal is requested:

$ acme.sh --install-cert --ecc -d yourdomain.com -d mail.yourdomain.com \
   --cert-file $(pwd)/.docker/nginx/tls_cert.pem \
   --key-file $(pwd)/.docker/nginx/tls_key.pem \
   --fullchain-file $(pwd)/.docker/nginx/tls_fullchain.pem \
   --reloadcmd "$(command -v docker-compose) -f $(pwd)/docker-compose.yml exec -T nginx nginx -s reload"

We should be good to go now. If there are docker-compose errors, just ignore them for now. We need to have Acme.sh restart Nginx whenever it fetches new certificates.

Step 4. Install Server Necessities

We will now try and configure the necessities for Mastodon to run.

Set up docker-compose.yml

First up, open up $ nano docker-compose.yml (or instead of nano, use vim or emacs or whatever you prefer) and paste the following, replacing yourdomain.com with your domain name:

version: '2.4'
services:

  nginx:
    restart: always
    image: nginx:mainline
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./public:/var/www/html:ro
      - ./.docker/nginx/nginx.conf:/tmp/nginx.conf:ro
      - ./.docker/nginx/tls_cert.pem:/etc/ssl/cert.pem:ro
      - ./.docker/nginx/tls_key.pem:/etc/ssl/key.pem:ro
      - ./.docker/nginx/tls_fullchain.pem:/etc/ssl/fullchain.pem:ro
    environment:
      - NGINX_HOST=yourdomain.com
      - TLS_PROTOCOLS="TLSv1.2 TLSv1.3"
      - TLS_CIPHERS="AES256+EECDH:AES256+EDH:!aNULL"
      - TLS_ECDH_CURVE="X25519:secp384r1"
    ports:
      - "80:80"
      - "443:443"
    command: sh -c "envsubst \"`env | awk -F = '{printf \" $$%s\", $$1}'`\" < /tmp/nginx.conf > /etc/nginx/conf.d/default.conf && nginx -g 'daemon off;'"
    networks:
      - external_network
      - rails_network
      - rainloop_network
      - streaming_network

  ipv6nat:
    restart: always
    image: robbertkl/ipv6nat
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /lib/modules:/lib/modules:ro
    privileged: true
    network_mode: host

  rainloop:
    image: hardware/rainloop
    restart: unless-stopped
    depends_on:
      - mail
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./.docker/rainloop:/rainloop/data
    networks:
      - rainloop_network

  mail:
    image: tvial/docker-mailserver:latest
    restart: always
    hostname: mail
    domainname: yourdomain.com
    container_name: mail
    cap_add:
      - NET_ADMIN
    ports:
      - "25:25"
      - "143:143"
      - "587:587"
      - "993:993"
      - "4190:4190"
    environment:
      - ENABLE_SPAMASSASSIN=1
      - ENABLE_CLAMAV=1
      - ENABLE_FAIL2BAN=1
      - ENABLE_POSTGREY=1
      - ONE_DIR=1
      - DMS_DEBUG=0
      - ENABLE_MANAGESIEVE=1
      - SSL_TYPE=manual
      - SSL_CERT_PATH=/etc/ssl/cert.pem
      - SSL_KEY_PATH=/etc/ssl/key.pem
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./.docker/mail/data:/var/mail
      - ./.docker/mail/state:/var/mail-state
      - ./.docker/mail/config:/tmp/docker-mailserver/
      - ./.docker/nginx/tls_cert.pem:/etc/ssl/cert.pem:ro
      - ./.docker/nginx/tls_key.pem:/etc/ssl/key.pem:ro
      - ./.docker/nginx/tls_fullchain.pem:/etc/ssl/fullchain.pem:ro
    networks:
      - rainloop_network
      - external_network

  db:
    restart: always
    image: postgres:10.3-alpine
    networks:
      - db_network
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./.docker/mastodon/db:/var/lib/postgresql/data

  redis:
    restart: always
    image: redis:4-alpine
    networks:
      - redis_network
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./.docker/mastodon/redis:/data
  
#### OPTIONAL AND REQUIRES A LOT OF MEMORY AND CPU ####
#  es:
#    image: docker.elastic.co/elasticsearch/elasticsearch-oss:6.2.3
#    restart: always
#    environment:
#      - bootstrap.memory_lock=true
#      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
#    ulimits:
#      memlock:
#        soft: -1
#        hard: -1
#    networks:
#      - es_network
#    volumes:
#      - /etc/localtime:/etc/localtime:ro
#      - ./.docker/mastodon/es:/usr/share/elasticsearch/data

  rails:
    image: tootsuite/mastodon:latest
    restart: always
    env_file: ./.docker/mastodon/.env.production
    environment:
      - WEB_CONCURRENCY=2
      - MAX_THREADS=15
    command: bash -c "rake db:migrate; rm -f /mastodon/tmp/pids/server.pid; bundle exec rails s -p 3000 -b '0.0.0.0'"
    networks:
      - db_network
      - redis_network
#      - es_network
      - rails_network
    depends_on:
      - db
      - redis
#      - es
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./public/assets:/mastodon/public/assets
      - ./public/packs:/mastodon/public/packs
      - ./public/system:/mastodon/public/system

  streaming:
    image: tootsuite/mastodon:latest
    restart: always
    env_file: ./.docker/mastodon/.env.production
    command: yarn start
    networks:
      - db_network
      - redis_network
      - streaming_network
    depends_on:
      - db
#      - es
      - redis
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./public/system:/mastodon/public/system

  sidekiq:
    image: tootsuite/mastodon:latest
    restart: always
    env_file: ./.docker/mastodon/env.production
    environment:
      - DB_POOL=10
    command: bundle exec sidekiq -q default -q mailers -q pull -q push
    depends_on:
      - db
#      - es
      - redis
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./public/assets:/mastodon/public/assets
      - ./public/packs:/mastodon/public/packs
      - ./public/system:/mastodon/public/system
    networks:
      - external_network
      - db_network
#      - es_network
      - redis_network

networks:
  external_network:
    driver: bridge
    enable_ipv6: true
    ipam:
      driver: default
      config:
        - subnet: 172.18.0.0/16
        - subnet: fd00:dead:beef::/48
  db_network:
    internal: true
#  es_network:
#    internal: true
  redis_network:
    internal: true
  streaming_network:
    internal: true
  rails_network:
    internal: true
  rainloop_network:
    internal: true

Now, there are a few explanations to this:

  1. Because we're running Mastodon and Nginx in a container, there are several components to this. As we're segmenting the network, none of the things listening on any of the servers are broadcasting to the outside world, in fact, it's not even broadcasting to your server.
  2. We're bridging to separate networks in separate containers based on what we need. Nginx cannot contact the Postgres container directly, but Redis can't contact Postgres either. In fact, the only three that can see the outside world are Nginx, Mailserver and Sidekiq.
  3. We don't need Elasticsearch - unless your server has a LOT of RAM and can handle the CPU load. If you think your server is powerful enough, you can uncomment the ES-specific lines above.

Pull all of the images related to the software above by running:

$ docker-compose pull

Set up the Mailserver

As noted, we're going to try setting up a mailserver for Mastodon to both send and receive emails. As a result, we use docker-mailserver as kind of a mail server in a box type of deal. (Note: If you do not require a mailserver and want to use something like Sendgrid or Mailgun, skip this step, and erase "rainloop" and "mail" containers from docker-compose.yml)

The next step in setting up docker-mailserver is to download the included setup.sh to help us set up and manage our mailserver. Run these commands first:

$ mkdir -p .docker/mail
$ docker-compose up -d mail
$ curl -o .docker/mail/setup.sh https://raw.githubusercontent.com/tomav/docker-mailserver/master/setup.sh
$ chmod a+x ./.docker/mail/setup.sh

Check to see that things are alright, not tampered with, etc. if paranoid:

$ less .docker/mail/setup.sh # (Hit Q if alright)

Now, we can create our admin account, by running:

$ cd .docker/mail; ./setup.sh add admin@yourdomain.com

Enter in a secure password. Next, set up DKIM and SPF. Run:

$ ./setup.sh config dkim 4096

Paste the domain records into the Vultr DNS that was explained in step 1. This is a way to sign and verify the mails that are coming and going from your domain.

Finally, let's start our mailserver:

$ cd ../..; docker-compose stop mail; docker-compose up -d mail

The server may lag as ClamAV updates and you may have to let it sit for a bit to gather updates. That's fine.

Exit out of the mastodon account back into privacc and run the following to allow the mail ports:

$ sudo ufw allow 25/tcp
$ sudo ufw allow 143/tcp
$ sudo ufw allow 587/tcp
$ sudo ufw allow 993/tcp
$ sudo ufw allow 4190/tcp

Then come back to mastodon:

$ sudo su - mastodon

Set up Nginx (again)

The next step is to set up the web server. As you've already set up docker-compose.yml, now you'll need to run:

$ nano .docker/nginx/nginx.conf

and insert the following:

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 80 default_server;
  listen [::]:80 default_server;

  server_name $NGINX_HOST;
  root /var/www/html;

  location /.well-known/acme-challenge/ {
      allow all;
      default_type "text/plain";
  }

  location / {
      return 301 https://$host$request_uri;
  }
}

# Remove this section if no mailserver
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;

  server_name mail.$NGINX_HOST;
  server_tokens off;

  ssl_protocols $TLS_PROTOCOLS;

  ssl_ciphers '$TLS_CIPHERS';
  ssl_ecdh_curve $TLS_ECDH_CURVE;
  ssl_prefer_server_ciphers on;

  ssl_session_cache shared:TLS:2m;
  ssl_session_timeout 10m;
  ssl_session_tickets off;

  ssl_stapling on;
  ssl_stapling_verify on;

  keepalive_timeout 70;
  sendfile on;
  client_max_body_size 0;

  add_header X-Frame-Options DENY;
  add_header X-Content-Type-Options nosniff;
  add_header X-XSS-Protection "1; mode=block";
  add_header Referrer-Policy "same-origin";
  add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
  add_header Access-Control-Allow-Origin "https://$host";

  ssl_certificate /etc/ssl/fullchain.pem;
  ssl_certificate_key /etc/ssl/key.pem;
  ssl_trusted_certificate /etc/ssl/cert.pem;

  resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001] valid=300s;
  resolver_timeout 5s;

  root /var/www/html;

  location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header Proxy "";
    proxy_pass_header Server;

    proxy_pass http://rainloop:8888;
    proxy_buffering off;
    proxy_redirect off;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    tcp_nodelay on;
  }
}

server {
  listen 443 ssl http2 default_server;
  listen [::]:443 ssl http2 default_server;

  server_name $NGINX_HOST;
  server_tokens off;

  ssl_protocols $TLS_PROTOCOLS;

  ssl_ciphers '$TLS_CIPHERS';
  ssl_ecdh_curve $TLS_ECDH_CURVE;
  ssl_prefer_server_ciphers on;

  ssl_session_cache shared:TLS:2m;
  ssl_session_timeout 10m;
  ssl_session_tickets off;

  ssl_stapling on;
  ssl_stapling_verify on;

  keepalive_timeout 70;
  sendfile on;
  client_max_body_size 0;

  add_header X-Frame-Options DENY;
  add_header X-Content-Type-Options nosniff;
  add_header X-XSS-Protection "1; mode=block";
  add_header Referrer-Policy "same-origin";
  add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
  add_header Access-Control-Allow-Origin "https://$host";
  add_header X-Cache-Status $upstream_cache_status;

  ssl_certificate /etc/ssl/fullchain.pem;
  ssl_certificate_key /etc/ssl/key.pem;
  ssl_trusted_certificate /etc/ssl/cert.pem;

  resolver 1.1.1.1 1.0.0.1 [2606:4700:4700::1111] [2606:4700:4700::1001] valid=300s;
  resolver_timeout 5s;

  root /var/www/html;

  location / {
    try_files $uri @proxy;
  }

  location /sw.js {
    add_header Cache-Control "public, max-age=0";
    try_files $uri @proxy;
  }

  location ~ ^/(emoji|packs|sounds|system/media_attachments|system/preview_cards) {
    add_header Cache-Control "public, max-age=31536000, immutable";

    gzip on;
    gzip_disable "msie6";
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    try_files $uri @proxy;
  }

  location @proxy {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header Proxy "";
    proxy_pass_header Server;

    proxy_pass http://rails:3000;
    proxy_buffering on;
    proxy_redirect off;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_cache CACHE;
    proxy_cache_valid 200 7d;
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
    proxy_cache_lock on;
    proxy_cache_revalidate on;

    tcp_nodelay on;
  }

  location /api/v1/streaming {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header Proxy "";

    proxy_pass http://streaming:4000;
    proxy_buffering off;
    proxy_redirect off;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    tcp_nodelay on;
  }

  error_page 403 /assets/403.html;
  error_page 404 /assets/404.html;
  error_page 410 /assets/410.html;
  error_page 422 /assets/422.html;
  error_page 500 501 502 503 504 /assets/500.html;
}

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=CACHE:10m inactive=7d max_size=2g use_temp_path=off;

You should be good to go.

Step 5. Install Mastodon

We're now ready to install Mastodon.

Go through the Setup Guide

Mastodon has a built in setup wizard that we can use.

Optional: Rake commands to modify Mastodon via the command-line usually begin with docker-compose run --rm rails rake, so I generally shorthand this for myself by doing:

$ echo "alias mastorake='$(command -v docker-compose) -f $(pwd)/docker-compose.yml run --rm rails rake'" >> ~/.bashrc
$ . ~/.bashrc

For the purposes of the rest of the tutorial if you don't want to do this, mastorake will be a shorthand for docker-compose run --rm rails rake, but it's entirely up to you.

Note: There are many times where Mastodon will try running what's known as Webpack to compile all assets into a few files. This frequently takes up a LOT of RAM and CPU, and will fail. If you feel like you don't have a lot of RAM free, you can enable swap space for now. Exit out of the mastodon account via $ exit and in your privacc user, run the following:

$ sudo fallocate -l 1G /swapfile
$ sudo chmod 600 /swapfile
$ sudo mkswap /swapfile
$ sudo swapon /swapfile

Then simply come back to the mastodon user via:

$ sudo su - mastodon

With that being said, run the following:

$ mastorake mastodon:setup

Go through every step. Domain name, Single user mode. When it asks you if you're using Docker to run Mastodon, say yes. The PostgreSQL host, port, name and username and password should all be default (aka, just hit Enter). Same for Redis.

Mastodon will then prompt you if you want to store uploaded files in the cloud. If you've already got something ready, go ahead, otherwise hit no. (There is also a way to choose Amazon S3 if you ever change your mind.)

If you set up the mailserver: You will also be asked if you want to send emails from localhost. Choose No. The SMTP server should be mail with a port of 587 and the username and password should be what you have provided when doing ./setup.sh email add. For SMTP authentication, choose starttls. SMTP OpenSSL verify mode should be set to none.

At the end, Mastodon will print out a configuration file between Below is your configuration, save it to an .env.production file outside Docker: and It is also saved within this container so you can proceed with this wizard.. Copy all of this, paste it into a Notepad for later. You will need this.

The next step will create the database. Just sit back for a couple of minutes.

The final step is creating CSS/JS assets via Webpack. This is the one that's going to be heavy on CPU and RAM, and also going to take anywhere from 5 to 30 minutes.

If you get "That failed! Maybe you need swap space?": See the comments above on setting up a swapfile via privacc. You're not doomed, but you're going to have to run $ mastorake assets:precompile right after you exit the Setup wizard.

When you get the Compiled all packs in /mastodon/public/packs message, you can breathe easy. If you did the swapfile instructions above, you can disable it by exiting out of your mastodon account and running this as privacc:

$ sudo swapoff /swapfile
$ sudo rm /swapfile

And then coming back to the mastodon user:

$ sudo su - mastodon

If, however, you got a "Compiled all packs" message, opt to create an admin user straight away.

Open up .docker/mastodon/.env.production via nano and paste what the setup wizard gave you earlier.

Start Everything

Now that Mastodon is set up, just simply run:

$ docker-compose down

Then:

$ docker-compose up -d

Navigate to https://yourdomain.com/ and you should be presented with a login prompt. If everything works well, consider submitting your new instance to the HSTS Preload List.

Note: If you installed the mailserver, navigate to https://mail.yourdomain.com/?admin and log in with the credentials "admin" and password "12345". (Please change them asap!) Navigate to Domains, delete all existing domains and then add your mail domain. The IMAP and SMTP server should be just "mail", but leave the ports be. The methods should all be "STARTTLS".

(Optional) Set up Unattended Upgrades for Ubuntu

Want to automatically fetch and apply server updates? Ubuntu comes with a tool named unattended-upgrades that allows just that.

Exit out of the mastodon user. As privacc, enter in:

$ sudo nano /etc/apt/apt.conf.d/50unattended-upgrades

Uncomment everything in the Allowed-Origins block.

Find Remove-Unused-Dependencies, uncomment the // and set it to true

Find Automatic-Reboot, uncomment, and set it to true

Find Automatic-Reboot-Time, uncomment, and set it to a time in 24-hour UTC that your instance will receive the least traffic.

Exit out, save, and then run:

$ sudo nano /etc/apt/apt.conf.d/20auto-upgrades

Paste the following:

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
APT::Periodic::Download-Upgradeable-Packages "1";

Exit out and save. To apply all of this, restart the server like so:

$ sudo shutdown -r now

(Optional) Automatically update Docker Compose

Run the following as privacc:

$ sudo nano /etc/cron.weekly/compose-upgrade && sudo chmod +x /etc/cron.weekly/compose-upgrade

Paste the following:

#!/bin/bash

COMPOSE_VERSION=`git ls-remote https://github.com/docker/compose | grep refs/tags | grep -oP "[0-9]+\.[0-9][0-9]+\.[0-9]+$" | tail -n 1`
sh -c "curl -L https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose" >/dev/null 2>&1
chmod a+x /usr/local/bin/docker-compose
sh -c "curl -L https://raw.githubusercontent.com/docker/compose/${COMPOSE_VERSION}/contrib/completion/bash/docker-compose > /etc/bash_completion.d/docker-compose" >/dev/null 2>&1

Exit and save.

(Optional) Backup Scripts

Courtesy of @rtucker, there's a backup script that I use to backup the PostgreSQL database and export it in such a way that my backup system will pick it up:

$ mkdir $(pwd)/backups

then, as backup.sh:

#!/bin/bash

[ -z "$BACKUP_LOC" ] && BACKUP_LOC="$HOME/backups"
[ ! -e "$BACKUP_LOC" ] && mkdir -p $BACKUP_LOC

[ -z "$COMPOSE" ] && COMPOSE="$(command -v docker-compose)"
[ -z "$COMPOSE" ] && COMPOSE="/usr/local/bin/docker-compose"

[ -z "$YML_LOC" ] && YML_LOC="$HOME/docker-compose.yml"

COMPOSE="$COMPOSE -f $YML_LOC"

if [ "$1" == 'daily' ]; then
  find $BACKUP_LOC -type f -name postgres-daily.* -mtime +7 -delete
  $COMPOSE exec -T -u postgres db sh -c "umask 0377 && /usr/local/bin/pg_dump -Fc -h db -d postgres -U postgres" > "$BACKUP_LOC/postgres-daily.$(date -Iseconds).pgsql"
  $COMPOSE run -T --rm rails rake mastodon:media:remove_remote
fi

if [ "$1" == 'hourly' ]; then
  find $BACKUP_LOC -type f -name postgres-hourly.* -mmin +360 -delete
  $COMPOSE exec -T -u postgres db sh -c "umask 0377 && /usr/local/bin/pg_dump -Fc -h db -d postgres -U postgres" > "$BACKUP_LOC/postgres-hourly.$(date -Iseconds).pgsql"
fi

Then just run chmod +x backup.sh. Finally, just insert these entries into crontab -e below:

0 * * * * /path/to/your/backup.sh hourly
0 0 * * * /path/to/your/backup.sh daily

You can also prepend COMPOSE_LOC=/path/to/docker-compose, YML_LOC=/path/to/my/docker-compose.yml, BACKUP_LOC=/home/mastodon/backups to each command to specify somewhere else.

Addendum: Updating Mastodon

You can update individual containers by calling docker-compose pull CONTAINERNAME (e.g. CONTAINERNAME being nginx, rails, etc.) and then re-creating the container and starting it with a docker-compose up -d CONTAINERNAME

To update and restart everything, just omit CONTAINERNAME from above.

The Docker Compose script should take care of checking to see if there are database updates before booting up the web service container. Regardless, you will need to run mastorake assets:precompile (aka docker-compose run --rm rails rake assets:precompile) each time that the Mastodon containers download an update.

Hard Mode (advanced users)

If you want to push the job of compiling all CSS/JS assets onto Docker Hub:

  1. Fork the Mastodon repository on GitHub,
  2. Open up Dockerfile, find ENTRYPOINT,
  3. Add before that line: RUN OTP_SECRET=_ SECRET_KEY_BASE=_ rake assets:precompile
  4. Remove /mastodon/public/assets and /mastodon/public/packs from the VOLUME command.
  5. Commit the changes.
  6. Head to Docker Hub, sign up, and head to Create > Create Automated Build.
  7. Select your GitHub username, and the Mastodon repository you forked and committed to.
  8. On the new Docker image you've created, press "Trigger" on the build.
  9. Wait about an hour.
  10. In your docker-compose.yml file, replace tootsuite/mastodon with dockerhubusername/mastodon (with dockerhubusername being the username you used for Docker Hub). Remove the references to mounting ./public/assets to /mastodon/public/assets, same with public/packs.
  11. Do a docker-compose pull followed by docker-compose up -d to re-create the containers.
  12. Enjoy almost-zero-downtime deployment.

Caveat is that you'll have to keep up with merging commits from upstream, but that should trigger builds automatically each time. There might also be other images with pre-built assets (vulpineclub/mastodon and pluralcafe/mastodon), but those are specific to those instances and use any images that aren't tootsuite's at your own risk.

Questions?

Contact @isatis@vulpine.club or @KT@plural.cafe with any questions, comments or suggestions.