3/19/2019 Installation - Mastodon documentation

Installation

• Basic server setup (optional)

• Do not allow password-based SSH login (keys only)

• Update system packages

• Install fail2ban so it blocks repeated login attempts

User guide • Install a rewall and only whitelist SSH, HTTP and HTTPS ports

Administrator guide • Pre-requisites

• System repositories
Installation
• Node.js
Con guration

• Yarn
Post-installation steps

Scaling up • System packages

Optional features
• Installing Ruby
Upgrading to a new release
• Setup
Migrating servers

• Setting up PostgreSQL
Troubleshooting

• Performance con guration (optional)

Development guide
• Creating a user

API Overview
• Setting up Mastodon

REST API • Checking out the code

• Installing the last dependencies

• Generating a con guration

• Setting up nginx

• Acquiring a SSL certi cate

• Setting up systemd services

https://docs.joinmastodon.org/administration/installation/ 1/11
3/19/2019 Installation - Mastodon documentation

Basic server setup (optional)

If you are setting up a fresh machine, it is recommended that you secure

it rst. Assuming that you are running Ubuntu 18.04:

Do not allow password-based SSH login (keys only)

First make sure you are actually logging in to the server using keys and
not via a password, otherwise this will lock you out. Many hosting
providers support uploading a public key and automatically set up key-
based root login on new machines for you.

Edit /etc/ssh/sshd_config and nd PasswordAuthentication . Make

sure it’s uncommented and set to no . If you made any changes, restart
sshd:

systemctl restart ssh

Update system packages

https://docs.joinmastodon.org/administration/installation/ 2/11
3/19/2019 Installation - Mastodon documentation

apt update && apt upgrade -y

Install fail2ban so it blocks repeated login attempts

apt install fail2ban

Edit /etc/fail2ban/jail.local and put this inside:

[DEFAULT]

destemail = your@email.here

sendername = Fail2Ban

[sshd]

enabled = true

port = 22

[sshd-ddos]

enabled = true

port = 22

Finally restart fail2ban:

systemctl restart fail2ban

Install a rewall and only whitelist SSH, HTTP and

HTTPS ports

First, install iptables-persistent. During installation it will ask you if you

want to keep current rules–decline.

apt install -y iptables-persistent

Edit /etc/iptables/rules.v4 and put this inside:

https://docs.joinmastodon.org/administration/installation/ 3/11
3/19/2019 Installation - Mastodon documentation

*filter

# Allow all loopback (lo0) traffic and drop all traffic to 12

-A INPUT -i lo -j ACCEPT

-A INPUT ! -i lo -d 127.0.0.0/8 -j REJECT

# Accept all established inbound connections

-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Allow all outbound traffic - you can modify this to only al

-A OUTPUT -j ACCEPT

# Allow HTTP and HTTPS connections from anywhere (the normal

-A INPUT -p tcp --dport 80 -j ACCEPT

-A INPUT -p tcp --dport 443 -j ACCEPT

# Allow SSH connections

# The -dport number should be the same port number you set in

-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT

# Allow ping

-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT

# Log iptables denied calls

-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables

# Reject all other inbound - default deny unless explicitly a

-A INPUT -j REJECT

-A FORWARD -j REJECT

COMMIT

With iptables-persistent, that con guration will be loaded at boot time.

But since we are not rebooting right now, we need to load it manually for
the rst time:

iptables-restore < /etc/iptables/rules.v4

https://docs.joinmastodon.org/administration/installation/ 4/11
3/19/2019 Installation - Mastodon documentation

Pre-requisites

• A machine running Ubuntu 18.04 that you have root access to

• A domain name (or a subdomain) for the Mastodon server, e.g.

example.com

• An e-mail delivery service or other SMTP server

You will be running the commands as root. If you aren’t already root,
switch to root:

sudo -i

System repositories

Make sure curl is installed rst:

apt install -y curl

Node.js

curl -sL https://deb.nodesource.com/setup_8.x | bash -

Yarn

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key ad

echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /e

System packages

apt update

apt install -y \

imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file g

g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc

bison build-essential libssl-dev libyaml-dev libreadline6-de

https://docs.joinmastodon.org/administration/installation/ 5/11
3/19/2019 Installation - Mastodon documentation

zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev \

nginx redis-server redis-tools postgresql postgresql-contrib

certbot yarn libidn11-dev libicu-dev libjemalloc-dev

Installing Ruby

We will be using rbenv to manage Ruby versions, because it’s easier to

get the right versions and to update once a newer release comes out.
rbenv must be installed for a single Linux user, therefore, rst we must
create the user Mastodon will be running as:

adduser --disabled-login mastodon

We can then switch to the user:

su - mastodon

And proceed to install rbenv and rbenv-build:

git clone https://github.com/rbenv/rbenv.git ~/.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 https://github.com/rbenv/ruby-build.git ~/.rbenv/plu

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

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.6.0

rbenv global 2.6.0

Default gem version shipped with ruby_2.6.0 is incompatible with latest

bundler, so we need to update gem:

https://docs.joinmastodon.org/administration/installation/ 6/11
3/19/2019 Installation - Mastodon documentation

gem update --system

We’ll also need to install bundler:

gem install bundler --no-document

Return to the root user:

exit

Setup

Setting up PostgreSQL

Performance con guration (optional)

For optimal performance, you may use pgTune to generate an appropriate

con guration and edit values in
/etc/postgresql/9.6/main/postgresql.conf before restarting

PostgreSQL with systemctl restart postgresql

Creating a user

You will need to create a PostgreSQL user that Mastodon could use. It is
easiest to go with “ident” authentication in a simple setup, i.e. the
PostgreSQL user does not have a separate password and can be used by
the Linux user with the same username.

Open the prompt:

sudo -u postgres psql

In the prompt, execute:

https://docs.joinmastodon.org/administration/installation/ 7/11
3/19/2019 Installation - Mastodon documentation

CREATE USER mastodon CREATEDB;

\q

Done!

Setting up Mastodon

It is time to download the Mastodon code. Switch to the mastodon user:

su - mastodon

Checking out the code

Use git to download the latest stable release of Mastodon:

git clone https://github.com/tootsuite/mastodon.git live && cd

git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | ta

Installing the last dependencies

Now to install Ruby and JavaScript dependencies:

bundle install \

-j$(getconf _NPROCESSORS_ONLN) \

--deployment --without development test

yarn install --pure-lockfile

Generating a con guration

Run the interactive setup wizard:

RAILS_ENV=production bundle exec rake mastodon:setup

This will:

https://docs.joinmastodon.org/administration/installation/ 8/11
3/19/2019 Installation - Mastodon documentation

• Create a con guration le

• Run asset precompilation

• Create the database schema

The con guration le is saved as .env.production . You can review and

edit it to your liking. Refer to the documentation on con guration.

You’re done with the mastodon user for now, so switch back to root:

exit

Setting up nginx

Copy the con guration template for nginx from the Mastodon directory:

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

ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-ena

Then edit /etc/nginx/sites-available/mastodon to replace

example.com with your own domain name, and make any other

adjustments you might need.

Reload nginx for the changes to take effect:

systemctl reload nginx

Acquiring a SSL certi cate

We’ll use Let’s Encrypt to get a free SSL certi cate:

certbot certonly --webroot -d example.com -w /home/mastodon/li

You can now edit /etc/nginx/sites-available/mastodon to

uncomment and adjust the ssl_certificate and

https://docs.joinmastodon.org/administration/installation/ 9/11
3/19/2019 Installation - Mastodon documentation

ssl_certificate_key lines.

Then, reload nginx for the changes to take effect:

systemctl reload nginx

At this point you should be able to visit your domain in the browser and
see the elephant hitting the computer screen error page. This is because
we haven’t started the Mastodon process yet.

Setting up systemd services

Copy the systemd service templates from the Mastodon directory:

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

Then edit the les 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:

systemctl start mastodon-web mastodon-sidekiq mastodon-streami

systemctl enable mastodon-*

They will now automatically start at boot time.

Hurray! This is it. You can visit your domain in the browser now!

Last updated February 3, 2019 · Improve this page

https://docs.joinmastodon.org/administration/installation/ 10/11
3/19/2019 Installation - Mastodon documentation

Merch
T-shirts and stickers

View source · CC BY-SA 4.0 · Imprint Join Mastodon · Find Twitter friends · Blog ·  ·  · 

https://docs.joinmastodon.org/administration/installation/ 11/11