Mastodon Docker Install


Jun 15, 2021 Run docker-compose build. Set correct file-owner with chown -R 991:991 public; Building the app. Now the image can be used to generate a configuration with: docker-compose run -rm web bundle exec rake mastodon:setup This is an interactive wizard that will guide you through the basic and necessary options and generate new app secrets. The official Mastodon docs have a guide to auto-renewing your certificate with cron. Starting Mastodon and migrating. Run this command to start the containers: # docker-compose up -d. Now run the migrations, as detailed on the github readme: # docker-compose run -rm web rails db:migrate # docker-compose run -rm web rails assets:precompile. Yes, as usual all I had to do was give up and post a question on SE to start making headway. Right after I posted this I tried adding the environment variable to docker-compse.yml, and also updated the postgres host to mastodondb1 (I had to make a similar update to the redis host). Nov 23, 2020 Install Mastodon. Mastodon can be built from source and run or it can be run from existing Docker containers. Because you can easily mix up the master branch with the currently released version that’s stable I suggest doing a mixture of the two things – fetching the source from Github and using it as your basis for running the pre-built. Apt-get install postgresql postgresql-contrib -y. Once installed, log in to PostgreSQL with the following command: su - postgres. [email protected]:$ psql. Psql (11.5 (Debian 11.5-1+deb10u1)) Type 'help' for help. Next, create a user for Mastodon with the following command: postgres=# CREATE USER mastodon CREATEDB.

Setting up

Clone Mastodon's repository.

Review the settings in docker-compose.yml. Note that it is not default to store the postgresql database and redis databases in a persistent storage location. If you plan on running your instance in production, you must uncomment the volumes directive in docker-compose.yml.

Mastodon Docker Install

Getting the Mastodon image

Using a prebuilt image

If you're not making any local code changes or customizations on your instance, you can use a prebuilt Docker image to avoid the time and resource consumption of a build. Images are available from Docker Hub: https://hub.docker.com/r/tootsuite/mastodon/

To use the prebuilt images:

  1. Open docker-compose.yml in your favorite text editor.
    1. Comment out the build: . lines for all images (web, streaming, sidekiq).
    2. Edit the image: tootsuite/mastodon lines for all images to include the release you want. The default is latest which is the most recent stable version, however it recommended to explicitly pin a version: If you wanted to use v2.2.0 for example, you would edit the lines to say: image: tootsuite/mastodon:v2.2.0
    3. Save the file and exit the text editor.
  2. Run cp .env.production.sample .env.production to bootstrap the configuration. Edit the correct values now.
  3. Run docker-compose build. It will now pull the correct image from Docker Hub.
  4. Set correct file-owner with sudo chown -R 991:991 public/system

Building your own image

You must build your own image if you've made any code modifications. To build your own image:

  1. Open docker-compose.yml in your favorite text editor.
    1. Uncomment the build: . lines for all images (web, streaming, sidekiq) if needed.
    2. Save the file and exit the text editor.
  2. Run cp .env.production.sample .env.production to bootstrap the configuration. Edit the correct values now.
  3. Run docker-compose build.
  4. Set correct file-owner with chown -R 991:991 public

Building the app

Now the image can be used to generate a configuration with:

This is an interactive wizard that will guide you through the basic and necessary options and generate new app secrets. At some point it will output your configuration, copy and paste that configuration into the .env.production file.

The wizard will setup the database schema and precompile assets. After it's done, you can launch Mastodon with:

nginx Configuration

You need to configure nginx to serve your Mastodon instance.

Reminder: Replace all occurrences of example.com with your own instance's domain or sub-domain.

cd to /etc/nginx/sites-available and open a new file:

nano /etc/nginx/sites-available/example.com.conf

Copy and paste the following and make edits as necessary:

Activate the nginx configuration added:

This configuration makes the assumption you are using Let's Encrypt as your TLS certificate provider.

If you are going to be using Let's Encrypt as your TLS certificate provider, see thenext sub-section. If not edit the ssl_certificate and ssl_certificate_key valuesaccordingly.

Let's Encrypt

This section is only relevant if you are using Let's Encryptas your TLS certificate provider.

Generation Of The Certificate

We need to generate Let's Encrypt certificates.

Make sure to replace any occurrence of 'example.com' with your Mastodon instance's domain.

Make sure that nginx is stopped at this point:

We will be creating the certificate twice, once with TLS SNI validation in standalone mode and the second time we will be using the webroot method. This is required due to the waynginx and the Let's Encrypt tool works.

After that successfully completes, we will use the webroot method. This requires nginx to be running:

Mastodon docker installation

Automated Renewal Of Let's Encrypt Certificate

Let's Encrypt certificates have a validity period of 90 days.

You need to renew your certificate before the expiration date. Not doing so will make users of your instance unable to access the instance and users of other instances unable to federate with yours.

We can create a cron job that runs daily to do this:

Copy and paste this script into that file:

Save and exit the file.

Make the script executable and restart the cron daemon so that the script runs daily:

That is it. Your server will renew your Let's Encrypt certificate.


A minimal set of commands I had to do to successfully run Mastodon viadocker-compose on the VPS. Many OS specific configurations are omitted, asI decided to use Arch on this VPS as well, which is not what most peoplechoose for their server environment, at least not whencaveatsof such choice play a major role.

Getting started

Clone the Mastodon repository. It contains a docker-compose.yml file aswell as other files directly or indirectly referenced by it (for examplepackage.json or yarn.lock):

Now here's what I occasionally do to help me keep track of the changes tothe configuration files easily. Make a branch on a given tag, which at thetime of writing was v3.4.1:

Without creating a branch, the HEAD would be in a detached state (pointingat a tagged commit, not a branch), It would still track changes, but thesewould not be accessible after another checkout.

Tip: toget the latest available tag easily,you can use git rev-list as follows:

Also consider changing the mastodon image to some tagged version. In thesection web replace mastodon:latest image with the tagged one:

It is useful for referencing and searching for issues, should some arise,at the very least. Even more important to me is that it requires a manualintervention to bump a version number, so things won't suddenly change whenthe docker-compose script get restarted without you understanding why. Itis overall a good practice to avoid unnecessary surprises.

Postgres database

The referenced version of postgres in the docker-compose file is9.6-alpine. This might work, but I tested with 12.5-alpine instead andfound no problems so far, so I changes to this version under the dbsection:

Start the container to setup the user, assuming the path to thedocker-compose file is /home/mastodon/mastodon/docker-compose.yml. Ifnot, modify the path so the postgres volume folder matches it. Considersetting a custom password:

Create a mastodon database user, use the password from above:


This makes database setup complete.

Set up Mastodon

Docker Install Windows

This part is a little bit tricky, as it took me the most time to figure outright:

Fill the domain name you intend to run the instance. This one is probablyhard to change once the instance is running. Fill the next questionsaccording to the table below:

QuestionType in
Do you want to enable single user mode?No
Are you using Docker to run Mastodon?Yes
PostgreSQL host:mastodon_db_1
PostgreSQL port:5432
Name of PostgreSQL database:mastodon
Name of PostgreSQL user:mastodon
Password of ProstgreSQL user:password

The above part should look like this in the terminal:

The setup then continues with email capabilities configuration questions. Iam omitting details for this part, as my emailprovider required different SMTP settings,some of which were not offered via this setup wizard. I have not found areliable way to send a test email from the UI or the console later, so itmight be worth trying here to get the emails sent out. Setting up cloudstorage or email capabilities can be also safely skipped now and configuredlater, if you wish to do so, use these options:

QuestionType in
Do you want to store uploaded files on the cloud?No
Do you want to send e-mails from localhost?Yes
E-mail address to send e-mails 'from':Enter
Send a test e-mail with this configuration right now?No
Save configuration?Yes

Your terminal should resemble this:

The terminal then outputs the configuration, including secret keys. Copyand paste it into .env.production file in the cloned repository alreadycontaining postgres/ directory and docker-compose.yml file, amongothers.

The last part is to migrate the database and create an admin account.Answer Yes to both and proceed. The Mastodon instance admin userpassword will be generated and displayed, make sure to not lose it! If youlose it before logging in successfully, one way to obtain it again is todelete postgres/ folder and start over from thePostgres database step above.


Full-text search

This step is optional, although it is a nice addition to have a full-textsearch provided via ElasticSearch available. Edit the docker-compose.ymland uncomment two es related blocks:

Edit .env.production file and append the following:

The instance should now be ready to start.

First run

Docker Install Ubuntu

Start the whole stack, this can take a while:

This generates other files and folders, consider setting the permissionsfor them and start the instance again:

Now without any modifications on docker-compose.yml the instance shouldbe available under the port 3000. Configure the reverse proxy of yourchoice to terminate the SSL/TLS and to proxy the domain name inserted intothe wizard earlier to this port. You can also find some inspiration abouthow to do so in my previous articles under tags Nginx andespecially acme.sh, should you choose to use these two tomanage this task and the certificates for you.

To access the web user interface, insert the admin user name and thepassword generated earlier, and you are ready to have fun in the fediverse!


  • Most Viewed News

    • Install Aws Cli In Docker
    • Using Docker On Windows
    • Install Whatsapp On Mac