Skip to content

Setting Up Mastodon on a Linux Server – Launch Your Own Social Networking Platform

Discover how to set up a secure, self-hosted Mastodon social network on Debian-based servers for independent microblogging → Learn more now

12 November 20263 min read14 Views0 helpful

Introduction

Mastodon is free and open-source software for running self-hosted social networking services.

It offers microblogging features similar to the service X (formerly Twitter), provided by a variety of independently operated nodes called instances – each with its own code of conduct, terms of use, privacy policies, privacy settings, and moderation guidelines.

Info

This guide focuses on installation on a Debian-based distro. Examples include Debian and Ubuntu. The instructions vary depending on the operating system used.

System Requirements

To set up a Mastodon instance on your server, you need the following:

  • Domain
  • Linux-based server
  • Mail server

Preparing Your System

It is recommended to disable password login via SSH beforehand, as using password login on servers accessible from the internet poses a security risk. You can disable this in your server's web interface under Information -> Access & Security -> Disable Password Login.

Then update your packages with the following command:

Code
apt update && apt upgrade -y

Next, install Mastodon's dependencies:

bash
# System repositories
apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates
# Node.js
curl -sL https://deb.nodesource.com/setup_16.x | bash -
# PostgreSQL
wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list

After installing Mastodon's dependencies, install the necessary system packages with these two commands:

bash
apt update
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 libgdbm-dev \
  nginx redis-server redis-tools postgresql postgresql-contrib \
  certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev

Let the packages install; this may take some time. Then configure yarn, the package manager for the previously installed Node.js:

bash
corepack enable
yarn set version stable

Installing Ruby

We create a separate user because managing Ruby versions is much easier this way. First, create a user named mastodon with login disabled. Then switch to the mastodon user. Use these commands:

bash
# You can leave the fields empty
adduser --disabled-login mastodon
su - mastodon

Now install the Ruby manager rbenv, which greatly simplifies managing Ruby versions. Install it with these commands:

bash
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/plugins/ruby-build

After running these commands, you can install Ruby and bundler at the same time:

bash
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.3
rbenv global 3.0.3
gem install bundler --no-document

This may take a while, so enjoy a tea or coffee in the meantime. Afterward, you’re done with setup and can return to the root user with exit.

Configuring PostgreSQL

Mastodon uses PostgreSQL as its database system. Configure it as follows:

bash
sudo -u postgres psql

At the PostgreSQL prompt, enter:

sql
CREATE USER mastodon CREATEDB;
\q

Setting Up Mastodon

Switch back to the mastodon user:

bash
su - mastodon

Then download the latest Mastodon version with git using these two commands:

bash
git clone https://github.com/tootsuite/mastodon.git live && cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)

Next, install the latest Ruby and JavaScript dependencies:

bash
bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --pure-lockfile

Now create your Mastodon configuration file with:

bash
RAILS_ENV=production bundle exec rake mastodon:setup
Info

If database setup fails, please log into your Postgres database with sudo -u postgres psql and follow this guide: https://gist.github.com/amolkhanorkar/8706915

Then switch back to the root user with exit.

Configuring the Web Server

Now comes the tricky part: the web server configuration. First, create an A record and/or AAAA record in your DNS pointing directly to your server. Alternatively, you can point the root record to your server.

Then copy and enable the Mastodon web server configuration with these two commands:

bash
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon

Edit the file /etc/nginx/sites-available/mastodon with a text editor like vim or nano and replace example.com with your desired domain.

Next, obtain an SSL certificate for your domain easily with:

bash
certbot --nginx -d <your domain>

Enter your domain. You will be asked for some information. At the end, you will be asked whether HTTP requests should be automatically redirected to HTTPS – we recommend enabling this.

Creating the Mastodon Service

Finally, create a Mastodon system service. This is quite straightforward. Copy the default service configuration into your distribution’s service directory:

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

Enable and start your new services with these two commands:

sh
systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

After a reboot, your setup should be complete. Enjoy your instance!

FAQ

Frequently asked questions

You need your own domain, a Linux-based server, and a mail server.
Mastodon is free open-source software for running self-hosted social networking services with microblogging features similar to X (formerly Twitter), provided through independently operated instances.
Yes, it is recommended because password login on servers accessible from the internet is a security risk. You can disable it in the web interface under Information -> Access & Security -> Disable Password Login.

Feedback

Was this article helpful?

Your feedback helps us prioritize and improve content.

0 of 0 Users found this article helpful.

Personal support

Need more help than the guide provides?

Our ZAP support team knows your product — briefly describe your issue and we'll help you personally.

Zappy knows this guide and answers you right in the chat.