Installing a Mastodon Server on Ubuntu 20.04

Select distribution:
Traducciones al Español
Estamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.

Mastodon is an open-source and decentralized micro-blogging platform. Like Twitter, it lets users follow other users and post text, photos, and video content. Mastodon also allows you to create a non-profit social network based on open web standards and principles. Unlike Twitter, Mastodon is decentralized, meaning that its content is not maintained by a central authority.

What sets the Mastodon platform apart is its federated approach to social networking. Each Mastodon instance operates independently — anyone can create an instance and build their community. But users from different instances can still follow each other, share content, and communicate.

Mastodon participates in the Fediverse, a collection of social networks and other websites that communicate using the ActivityPub protocol. That allows different Mastodon instances to communicate, and also allows other platforms in the Fediverse to communicate with Mastodon.

Mastodon servers range in size from small private instances to massive public instances and typically center on specific interests or shared principles. The biggest Mastodon server is, a general-interest server created by the developers of the Mastodon platform. It has over 540,000 users and boasts a thorough Code of Conduct.

Before You Begin

  1. Familiarize yourself with our Getting Started with Linode guide and complete the steps for setting your Linode’s hostname and timezone.

  2. This guide uses sudo wherever possible. Complete the sections of our How to Secure Your Server guide to create a standard user account, harden SSH access, and remove unnecessary network services.

  3. Complete the steps in the Add DNS Records section to register a domain name to point to your Mastodon instance.

  4. Prepare an SMTP server for Mastodon to send email notifications to users when they register for the site, get a follower, receive a message, and for other Mastodon activity.

    • You can create your SMTP server — and even host it on the same machine as your Mastodon server — by following the Email with Postfix, Dovecot, and MySQL guide.

    • Alternatively, you can use a third-party SMTP service. This guide provides instructions for using Mailgun as your SMTP provider.

  5. Update your system.

     sudo apt update && sudo apt upgrade
  6. Replace occurrences of in this guide with the domain name you are using for your Mastodon instance.

This guide is written for non-root users. Commands that require elevated privileges are prefixed with sudo. If you’re not familiar with the sudo command, see the Linux Users and Groups guide.

Install Docker and Docker Compose

Mastodon can be installed using its included Docker Compose file. Docker Compose installs and runs all of the requisites for the Mastodon environment in Docker containers. If you have not used Docker before, it is recommended that you review the following guides:

Install Docker

To install Docker CE (Community Edition), follow the instructions within one of the guides below:

For complete instructions on even more Linux distributions, reference the Install Docker Engine section of Docker’s official documentation.

Install Docker Compose

  1. Download the latest version of Docker Compose. Check the releases page and replace 1.25.4 in the command below with the version tagged as Latest release:

     sudo curl -L`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
  2. Set file permissions:

     sudo chmod +x /usr/local/bin/docker-compose

Download Mastodon

  1. Clone the Mastodon Git repository into the home directory, and change it into the resulting Mastodon directory.

     cd ~/
     git clone
     cd mastodon

    Unless otherwise stated, all the Docker Compose-related commands to be run in this directory.

Configure Docker Compose

  1. Using your preferred text editor, open the docker-compose.yml file.

  2. Comment out the build lines (adding # in front of each), and append a release number to the end of each image: tootsuite/mastodon line as here: tootsuite/mastodon:v3.3.0.

    Although you can use latest as the release, it is recommended that you select a specific release number. The Mastodon GitHub page provides a chronological list of Mastodon releases.

  3. In the db section, add the following beneath the image line. Replace password with a password you would like to use for the PostgreSQL database that operates on the Mastodon backend.

       POSTGRES_PASSWORD: password
       POSTGRES_DB: mastodon_production
       POSTGRES_USER: mastodon
  4. The resulting docker-compose.yml file should resemble the example Docker file.

  5. Copy the .env.production.sample file (which is in the current mastodon directory) to create a new environment configuration file.

     cp .env.production.sample .env.production
  6. Use the following commands to generate a SECRET_KEY_BASE and OTP_SECRET. Copy the output, and paste it into the SECRET_KEY_BASE and OTP_SECRET lines in the .env.production file.

     echo SECRET_KEY_BASE=$(docker-compose run --rm web bundle exec rake secret)
     sed -i -e "s/SECRET_KEY_BASE=/&${SECRET_KEY_BASE}/" .env.production
     echo OTP_SECRET=$(docker-compose run --rm web bundle exec rake secret)
     sed -i -e "s/OTP_SECRET=/&${OTP_SECRET}/" .env.production
    $ echo SECRET_KEY_BASE=$(docker-compose run --rm web bundle exec rake secret)
    Creating mastodon_web_run ... done
    $ echo OTP_SECRET=$(docker-compose run --rm web bundle exec rake secret)
    Creating mastodon_web_run ... done
  7. Generate the VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY using the following command, and again copy the output, and paste it into the VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY lines in the .env.production file.

      docker-compose run --rm web bundle exec rake mastodon:webpush:generate_vapid_key
    $ docker-compose run --rm web bundle exec rake mastodon:webpush:generate_vapid_key
    Creating mastodon_web_run ... done
  8. Fill out the remaining fields of the .env.production file:

    • LOCAL_DOMAIN: Enter your Mastodon server’s domain name.

    • DB_PASS: Enter the password you set for the database in the docker-compose.yml file.

    • Enter mastodon_db_1 for DB_HOST and mastodon_redis_1 for REDIS_HOST. In both of these values, mastodon corresponds to the name of the Mastodon base folder.

    • Fill out the SMTP fields with the information from your SMTP provider. If you set up your SMTP server, use its domain name for SMTP_SERVER and add the following lines:


    Comment out the sections denoted as “optional” by adding a # before each line in the section.

  9. The resulting .env.production file should resemble the example environment file.

Complete the Docker Compose Setup

  1. Build the Docker Compose environment.

     docker-compose build
  2. Give ownership of the Mastodon public directory to user 991. This is the default user ID for Mastodon, and this command ensures that it has the necessary permissions.

     sudo chown -R 991:991 public
  3. Run Mastodon’s Docker Compose setup script. You are prompted to enter information about the Docker Compose services and the Mastodon instance.

     docker-compose run --rm web bundle exec rake mastodon:setup
    • Many prompts repeat fields you completed in the .env.production file. Make sure to enter the same information here as you entered in the file.

    • When prompted to create a Mastodon admin user account, choose to do so (Y). Enter the username, password, and email address you would like to use to access the account.

    • For any other prompts, enter the default values by pressing Enter.

Initiate the Docker Compose Services

  1. Start the Docker Compose services.

     docker-compose up -d
  2. Unless manually stopped, the Docker Compose services begin running automatically at system startup. Run the following command to manually stop the Docker Compose services:

     docker-compose down

Setup an HTTP/HTTPS Proxy

  1. Allow HTTP and HTTPS connection on the system’s firewall.

     sudo ufw allow http
     sudo ufw allow https
     sudo ufw reload
  2. Install NGINX, which proxies requests to your Mastodon server.

     sudo apt install nginx
  3. Copy the nginx.conf file included with the Mastodon installation to the sites-available NGINX folder; use your Mastodon domain name instead of in the file name:

     sudo cp ~/mastodon/dist/nginx.conf /etc/nginx/sites-available/
  4. Open the file with your preferred text editor, and replace all instances of with the domain name for your Mastodon site. This domain name must match the one you used to set up Docker Compose for Mastodon.

  5. Create a symbolic link of this file in the sites-enabled NGINX folder.

     cd /etc/nginx/sites-enabled
     sudo ln -s ../sites-available/

Get an SSL/TLS Certificate

Mastodon is served over HTTPS, so you need an SSL/TLS certificate. This guide uses Certbot to request and downloads a free certificate from Let’s Encrypt.

  1. Update the Snap app store. Snap provides application bundles that work across major Linux distributions and comes by default with all Ubuntu releases since 16.04:

     sudo snap install core && sudo snap refresh core
  2. Ensure that any existing Certbot installation is removed.

     sudo apt remove certbot
  3. Install Certbot.

     sudo snap install --classic certbot
  4. Download a certificate for your site.

     sudo certbot certonly --nginx

    Certbot prompts you to select from the NGINX sites configured on your machine. Select the one with the domain name you set up for your Mastodon instance.

  5. Certbot includes a chron job that automatically renews your certificate before it expires. You can test the automatic renewal with the following command.

     sudo certbot renew --dry-run
  6. Open the /etc/nginx/sites-available/ file again, and un-comment the ssl_certificate and ssl_certificate_key lines.

  7. Restart the NGINX server.

     sudo systemctl restart nginx

Using Mastodon

  1. In a web browser, navigate to your Mastodon site’s domain. You should see the Mastodon login page, where you can log in as the admin user you created earlier or create a new user.

    Mastodon login/sign-up page

  2. You can navigate to your instance’s administration page by navigating to The administration page allows you to alter the look, feel, and behavior of your instance.

    Mastodon administration page

  3. If your instance is running but having issues, you can troubleshoot them from the Sidekiq dashboard. Either select Sidekiq from the administration menu or navigate to to see the dashboard.

    Sidekiq dashboard

To learn more about Mastodon, check out the official Mastodon blog with news and articles related to Mastodon. You can engage with the Mastodon administrative community on Mastodon’s discussion forum, where you can peruse conversations about technical issues and community governance.

When you are ready to make your instance known to the world, you can add it to the list over at by filling out the admin form.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

This page was originally published on

Create a Linode account to try this guide with a $100 credit.
This credit will be applied to any valid services used during your first 60 days.

Your Feedback Is Important

Let us know if this guide made it easy to get the answer you needed.

Join the conversation.
Read other comments or post your own below. Comments must be respectful, constructive, and relevant to the topic of the guide. Do not post external links or advertisements. Before posting, consider if your comment would be better addressed by contacting our Support team or asking on our Community Site.