Mastodon is a free and open source self-hosted social network server licensed under AGPLv3. Mastodon is similar in features to Twitter and allows you to publish links, text, video and pictures and share in the globally interconnected microblogging community. In this post, we will discuss how to install Mastodon on Ubuntu 20.04/18.04 Linux secured with Let’s Encrypt SSL Certificate.

Mastodon has a number of dependencies that must be installed. They include Ruby, PostgreSQL, Node.js, Yarn, Redis, Nginx e.t.c. Our steps will discuss all the steps required to have a running Mastodon on Ubuntu 20.04/18.04 LTS.

Top Features of Mastodon

  • No vendor lock-in: Fully interoperable with any conforming platform
  • Real-time, chronological timeline updates: See the updates of people you’re following appear in real-time in the UI via WebSockets
  • Safety and moderation tools: Private posts, locked accounts, phrase filtering, muting, blocking and all sorts of other features, along with a reporting and moderation system.
  • Media attachments like images and short videos: Upload and view images and WebM/MP4 videos attached to the updates. Videos with no audio track are treated like GIFs; normal videos are looped – like vines!
  • OAuth2 and a straightforward REST API: Mastodon acts as an OAuth2 provider so 3rd party apps can use the REST and Streaming APIs, resulting in a rich app ecosystem with a lot of choices!

Setup Requirements

The following pieces of software are required when setting up Mastodon on Ubuntu 20.04/18.04 Linux.

  • PostgreSQL 9.5+
  • Redis
  • Ruby 2.4+
  • Node.js 8+

We assume you have the following ready as well.

  • A running Ubuntu 20.04/18.04 machine
  • A domain name (or a subdomain) for the Mastodon server, e.g. or
  • An e-mail delivery service or other SMTP server to use for notifications.

Step 1: Update System

Ensure your server is updated:

sudo apt -y update && sudo apt -y upgrade
sudo reboot

Step 2: Install Node.js & Yarn

Install Node.js

curl -sL | sudo bash -
sudo apt-get install -y nodejs

Confirm successful installation by checking the version:

$ nodejs --version

Install yarn:

curl -sS | sudo apt-key add -
echo "deb stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update
sudo apt -y install yarn

Step 3: Install other dependency packages

There are a number of system dependency packages required to run Mastodon on Ubuntu 20.04/18.04. Let’s ensure these packages are installed locally.

sudo apt install -y imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev nginx redis-server redis-tools certbot python-certbot-nginx yarn libidn11-dev libicu-dev libjemalloc-dev

Step 4: Install Ruby

The preferred way of running Ruby is with rbenv since it allows you to manage multiple versions easily. We’ll create a Mastodon user to be used for these operations.

sudo adduser --disabled-login mastodon
sudo su - mastodon

Then install rbenv and rbenv-build:

git clone ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone ~/.rbenv/plugins/ruby-build

Once this is done, we can install the correct Ruby version:

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.6.5
rbenv global 2.6.5

The default gem version shipped with ruby_2.6.0 is incompatible with latest bundler, so we need to update gem and install bundler.

gem update --system
gem install bundler --no-document

Step 5: Install PostgreSQL Database server

Use our PostgreSQL installation guide:

Install PostgreSQL database Ubuntu

Creating a user:

sudo -u postgres psql

Step 6: Setting up Mastodon

It is time to download the Mastodon code. First switch from root or your user account to the mastodon user:

sudo apt -y install git
sudo su - mastodon

Clone the Mastodon code:

git clone live && cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)

Installing the last dependencies:

gem install bundler:1.17.3
bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test
yarn install --pure-lockfile

Run the interactive wizard to generate a configuration:

RAILS_ENV=production bundle exec rake mastodon:setup

Fill required information:

/home/mastodon/.rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/bundler-1.17.3/lib/bundler/rubygems_integration.rb:200: warning: constant Gem::ConfigMap is deprecated
Your instance is identified by its domain name. Changing it afterward will break things.
Domain name:

Single user mode disables registrations and redirects the landing page to your public profile.
Do you want to enable single user mode? yes

Are you using Docker to run Mastodon? no

PostgreSQL host: /var/run/postgresql
PostgreSQL port: 5432
Name of PostgreSQL database: mastodon_production
Name of PostgreSQL user: mastodon
Password of PostgreSQL user: 
Database configuration works! 🎆

Redis host: localhost
Redis port: 6379
Redis password: 
Redis configuration works! 🎆

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": Mastodon <[email protected]>
Send a test e-mail with this configuration right now? no

This configuration will be written to .env.production
Save configuration? Yes

Agree to compile assets when prompted:


The final step is compiling CSS/JS assets.
This may take a while and consume a lot of RAM.
Compile the assets now? Yes
Running `RAILS_ENV=production rails assets:precompile` ...

/home/mastodon/.rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/bundler-1.17.3/lib/bundler/rubygems_integration.rb:200: warning: constant Gem::ConfigMap is deprecated
/home/mastodon/.rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/bundler-1.17.3/lib/bundler/rubygems_integration.rb:200: warning: constant Gem::ConfigMap is deprecated
/home/mastodon/.rbenv/versions/2.6.5/lib/ruby/gems/2.6.0/gems/bundler-1.17.3/lib/bundler/rubygems_integration.rb:200: warning: constant Gem::ConfigMap is deprecated
yarn install v1.21.1
[1/6] Validating package.json...
[2/6] Resolving packages...
[3/6] Fetching packages...
info [email protected]: The platform "linux" is incompatible with this module.
info "[email protected]" is an optional dependency and failed compatibility check. Excluding it from installation.
info [email protected]: The platform "linux" is incompatible with this module.
info "[email protected]" is an optional dependency and failed compatibility check. Excluding it from installation.
[4/6] Linking dependencies...
warning " > [email protected]" has incorrect peer dependency "[email protected]^3.0.0 || ^4.0.0 || ^5.0.0".
[5/6] Building fresh packages...
[6/6] Cleaning modules...
Done in 12.60s.

Agree to create admin account


All done! You can now power on the Mastodon server 🐘

Do you want to create an admin user straight away? Yes
Username: admin
E-mail: [email protected]
You can login with the password: 1b417e401f44c3db5d30f2f2f2a2328b
You can change your password once you login.

Upgrade yarn:

yarn upgrade

Step 7: Setting up nginx for Mastodon

We’ll use Nginx as a reverse proxy to our Mastodon application. Check if nginx service is running:

$ systemctl status nginx
● nginx.service - A high performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2020-01-07 08:25:31 UTC; 7h ago
     Docs: man:nginx(8)
 Main PID: 14626 (nginx)
    Tasks: 2 (limit: 2361)
   CGroup: /system.slice/nginx.service
           ├─14626 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
           └─14629 nginx: worker process

Now copy the configuration template for nginx from the Mastodon directory:

sudo cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon.conf

Edit the file to set correct DNS name for your application:

sudo vim /etc/nginx/sites-available/mastodon.conf

Once done, activate the configuration:

sudo ln -s /etc/nginx/sites-available/mastodon.conf /etc/nginx/sites-enabled/mastodon.conf
sudo systemctl restart nginx

If you have ufw firewall running, allow the service port:

sudo ufw allow 'Nginx Full'

Using Let’s Encrypt SSL Certificate

If you want to use a Let’s Encrypt Certificate, run the command below:

sudo certbot --nginx -d

Sample output:

$ sudo certbot --nginx -d
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator nginx, Installer nginx
Enter email address (used for urgent renewal and security notices) (Enter 'c' to
cancel): [email protected]

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at You must
agree in order to register with the ACME server at
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(A)gree/(C)ancel: A

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about our work
encrypting the web, EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: Y
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/mastodon.conf

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/mastodon.conf

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully enabled

You should test your configuration at:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

 - Congratulations! Your certificate and chain have been saved at:
   Your key file has been saved at:
   Your cert will expire on 2020-04-06. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot again
   with the "certonly" option. To non-interactively renew *all* of
   your certificates, run "certbot renew"
 - Your account credentials have been saved in your Certbot
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Certbot so
   making regular backups of this folder is ideal.
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:
   Donating to EFF:          

Substituting with your actual domain name for Mastodon application.

Step 8: Setting up systemd services

Copy the systemd service templates from the Mastodon directory:

sudo cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/

Then edit the files to make sure the username and paths are correct:

  • /etc/systemd/system/mastodon-web.service
  • /etc/systemd/system/mastodon-sidekiq.service
  • /etc/systemd/system/mastodon-streaming.service

Finally, start and enable the new systemd services:

sudo systemctl daemon-reload
for i in web sidekiq streaming; do sudo systemctl enable mastodon-$i && sudo systemctl restart mastodon-$i; done

Check status of all services:

for i in web sidekiq streaming; do systemctl status mastodon-$i; done

Step 9: Access Mastodon Dashboard

Now visit your domain in the browser to access Mastodon dashboard.

setup mastodon ubuntu 01

Click the login button to login. I’ll use the admin username email address and password generated earlier.

setup mastodon ubuntu 02

Go through initial tutorial to finish setup.

setup mastodon ubuntu 03
setup mastodon ubuntu 04

You should now be greeted with an awesome Mastodon dashboard.

setup mastodon ubuntu 05

Hurray!, You have successfully installed Mastodon on Ubuntu 20.04/18.04 Linux.


Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


Please enter your comment!
Please enter your name here