Run your own Mastodon server with Docker Compose


With the purchase of Twitter by Elon Musk, alternatives to Twitter suddenly become interesting. One of them is Mastodon an open source decentralized alternative that is part of the Fediverse. The decentralization is based on the fact that anyone can actually operate a Mastodon server.

This tutorial describes all the necessary steps to set up a Mastodon server with Docker Compose yourself.


This tutorial assumes that you already have some packages installed on your distribution:

  • Docker Compose
  • Git


First we clone the Mastodon Repository to a suitable location that you are free to choose:

cd /opt/
git clone
cd /opt/mastodon

Use specific version

If you want to use a specific Mastodon version you should check it out accordingly:

git checkout v4.0.2


Now we have to configure or set up our Mastodon server. To do this, we copy the configuration template:

cp .env.production.sample .env.production

We download all the necessary images:

docker-compose pull

Now we run the setup assistant of Mastodon:

docker-compose run --rm web bundle exec rake mastodon:setup


First you have to enter the domain of your Mastodon instance. This setting cannot be easily adjusted later, so choose wisely here.

In my case that would be:

Single User Mode

Now you have to decide whether you want to use your Mastodon server alone or whether you want to allow other users as well.


Now you will be asked if you are using Docker. In this case, of course, that would be “yes”.


Now it’s time to configure the PostgreSQL database


Here you can enter the host of an existing PostgreSQL server or simply confirm the preselection “db” with Enter to create a new one.


The port is entered here accordingly. If you don’t want to change it, simply confirm the preselection “5432” with Enter.


Choose a name or simply confirm with Enter.


Choose a name or simply confirm with Enter.


You should enter a secure password for the database here! I generate this myself with OpenSSL. Enter the following command in another console and copy the password accordingly:

openssl rand -base64 32


Now we need to configure the Redis server.


Here you can enter the host of your Redis server or simply create a new one by pressing Enter.


Of course, the same applies to the Redis port.


If the specified Redis server requires a password or you want to define one, you can do so now.

Files in Cloud

In principle, all uploaded files are stored on the computer on which the Mastodon server is running.

If you operate a multi-user system, a few data can quickly accumulate. You can therefore choose whether the uploaded files such as images, etc. should be stored in cloud storage such as an Amazon S3 Bucket.

In my case I don’t do it.


Especially with multi-user systems, an SMTP server must be set up so that things like registration and password reset can work properly.

If you want to specify an external SMTP server, you must answer the question with “N”.

SMTP Server

Enter the hostname of your SMTP server here.


Enter the port of your SMTP server here.

SMTP Username

Enter the user name or email address of your account on the SMTP server here. I have created a special email account for this purpose.

SMTP Password

Enter the password for your account here.

SMTP Authentication

Select the authentication method of the SMTP server here.


Here you have to select the verification method for the SMTP server certificate. The simplest would be “none”.

Email Address

Here you can now enter the externally visible email address in the form of “Mastodon”.

Test Email

Now you can choose whether you want to send a test email. You should definitely do this to know if everything is working correctly.

Configuration finished

Now the configuration of the Mastodon server is complete.


The setup assistant now asks if you want to create the database and at the same time warns that it will delete an existing database with the same name. So better check again if everything is correct!

Create Admin Account

You will now be asked if you want to create an admin account. You should definitely do that here. You will then receive a password with which you can log in. After the first login, the password should be changed!

File Permissions

Now we have to set a few necessary file permissions, otherwise the upload of images, for example, will not work:

chown -R 991:991 /opt/mastodon/public

Start Mastodon

To start your server, the container must be started:

docker-compose up -d

Setup Nginx Proxy

In my Nginx configuration I set up a proxy redirect to the Mastodon server.

location / {
	proxy_set_header HOST $host;
	proxy_set_header X-Forwarded-Proto https;
	proxy_set_header X-Real-IP $remote_addr;
	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	proxy_set_header X-Forwarded-Host $server_name;
	proxy_pass http://localhost:3000;

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 $scheme;
    proxy_set_header Proxy "";

    proxy_pass http://l "Socialmedia"ocalhost:4000;
    proxy_buffering off;
    proxy_redirect off;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    tcp_nodelay on;

Of course you should secure the Nginx server with an SSL certificate from Let’s Encrypt! But that should not be part of this tutorial.


We have now completed setting up our own Mastodon server.

Let’s toot…


You can use your Mastodon account to reply to this Post.