Running your own Mastodon instance with Docker

This is on a Ubuntu 22.04 server. Install the necessary Docker packages first.

sudo apt install docker-compose-v2

Add a mastodon user with UID and GID 991.

sudo groupadd -g 991 mastodon
sudo useradd -u 991 -g 991 -m -d /srv/mastodon -s /bin/false mastodon

Now cd to /srv/mastodon, clone the Mastodon repository and check out the current version.

git clone .
git checkout v4.2.8

Build the Mastodon image and set correct ownership of the public directory.

docker compose build
sudo chown -R mastodon: /srv/mastodon/public

Now run the Mastodon setup step.

copy .env.production.sample .env.production
docker compose run --rm web rake mastodon:setup

Fill in the necessary details but leave the Redis password blank. Make sure the (sub)domain you want to use has a proper DNS record. The setup outputs a set of variables, copy and paste those into .env.production after having deleted the old content. Since this file contains credentials you could chmod 400 it so only the user firing up the Docker setup has read access.

Start the Mastodon stack.

docker compose up -d

And verify all containers come up healthy. Now you can put your Mastodon instance behind a reverse proxy. I’m running Apache myself and the configuration below works for me. Bear in mind it relies on a working Let’s Encrypt certificate, you will have to create one yourself.

<VirtualHost *:80>
        AssignUserID mastodon mastodon # Only applicable when using MPM-ITK

        DocumentRoot /srv/mastodon

        <Directory />
                Options FollowSymLinks
                AllowOverride None

        Redirect permanent /

        ErrorLog ${APACHE_LOG_DIR}/

        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn

        CustomLog ${APACHE_LOG_DIR}/ combined


<VirtualHost *:443>
        AssignUserID mastodon mastodon # Only applicable when using MPM-ITK

        ProxyPreserveHost On
        ProxyPass /api/v1/streaming http://localhost:4000/
        ProxyPass / http://localhost:3000/
        ProxyPassReverse / http://localhost:3000/

        RequestHeader set X-Forwarded-Proto "https"

        SSLEngine on
        SSLProxyEngine on
        SSLCertificateFile      /etc/letsencrypt/live/
        SSLCertificateKeyFile   /etc/letsencrypt/live/
        SSLCertificateChainFile /etc/letsencrypt/live/

        # intermediate configuration, tweak to your needs
        SSLProtocol             all -SSLv3 -TLSv1 -TLSv1.1
        SSLHonorCipherOrder     off
        SSLCompression    off

        # HSTS (mod_headers is required) (15768000 seconds = 6 months)
        Header always set Strict-Transport-Security "max-age=15768000"

        ErrorLog ${APACHE_LOG_DIR}/
        CustomLog ${APACHE_LOG_DIR}/ combined

Reload Apache and visit your Mastodon instance with the admin account you created. The result of these steps can be found here:


Running your own Mastodon instance with Docker

Leave a Reply

Your email address will not be published. Required fields are marked *