How to Install Mastodon Social Network on Debian 11

Mastodon is a free, decentralized, and open-source social network similar to Twitter. In Mastodon, users can follow each other, and post messages, images, and videos. But unlike Twitter, there is no central store or authority for the content.

With the decentralized architecture, Mastodon operates across thousands of different servers each run by various members of the community. You can create your Mastodon server under your domain. You can also follow other users with different domains on the other servers.

In this tutorial, you'll install Mastodon, a decentralized microblogging platform on a Debian 11 server. With this guide, you'll set up Mastodon with PostgreSQL as the database server and Nginx as a reverse proxy. Also, you'll secure the Mastodon installation via free SSL certificates from Letsencrypt.

Prerequisites

This guide assumes that you have the following requirements in place:

• A Debian 11 server - this example uses the latest Debian 11 server with hostname 'mastodon-server' and the IP address '192.168.5.40'.
• A non-root user with sudo/root administrator privileges.
• A domain name pointed and resolved to your public Debian server - this example uses the sub-domain 'mastodon.howtoforge.local'.

When you have got those prerequisites in place, you're ready to go to the Mastodon installation.

Setting Up Repositories and Installing Dependencies

Mastodon is free and open-source software for running self-hosted social networking services that similar to Twitter service. It's mainly written in Ruby, especially with the Ruby on Rails web framework and JavaScript with Reac.js and Redux framework.

In this first step, you'll set up additional repositories to your system and install package dependencies for the Mastodon installation. This includes the package such as build-essentials for compiling Ruby, PostgreSQL for the database server, Nginx as the web server and reverse proxy, certbot tool for acquiring SSL certificates via Letsencrypt, and the Redis server that will be used for key-value store and session management for the Mastodon.

Before you get started, run the below apt command to install some basic dependencies that will be used for managing repositories and packages.

sudo apt install curl wget gnupg apt-transport-https lsb-release ca-certificates

When prompted, input y to confirm and press ENTER to proceed.

Next, run the below command to add the Node.js Nodesource repository. The Node.js package here will be used for compiling static assets of the Mastodon. And at the time of this writing, the latest Mastodon required at least Node.js v16.

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

You'll then receive the output like the following.

After the Node.js repository is added, you'll then set up the repository for the Yarn package manager. This repository provides the Yarn package that will be used to install JavaScript dependencies.

Run the below command to add the GPG key and the repository of the Yarn package manager.

curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

The third repository that you'll add is the PostgreSQL repository. Run the below command to add the PostgreSQL repository to your Debian server.

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

With the Node.js, Yarn, and PostgreSQL repositories added, run the below apt command to refresh your package index.

sudo apt update

You'll receive the output like this.

Lastly, run the below apt command to install package dependencies that will be used to install Mastodon.

sudo apt install 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 nodejs yarn redis-server redis-tools postgresql postgresql-contrib \
  certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev

Input y when prompted for the confirmation and press ENTER to proceed.

With this, you've installed basic dependencies for the Mastodon and added some third-party repositories to your Debian system.

In the next steps, you'll install Ruby via the rbenv - The Ruby version manager.

Installing rbenv and Ruby

rbenv is a version manager tool for the Ruby programming language on Unix-like systems. It is useful for switching between multiple Ruby versions on the same machine and for ensuring that each project you are working on always runs on the correct Ruby version.

To begin, run the below command to create a new user 'mastodon' on your system. This new user will be used to run services related to Mastodon, and the Mastodon source code will be stored in this user's home directory.

sudo adduser --disabled-login mastodon

During the process, you'll be asked for user details configuration. Input your user information and the input y to confirm and press ENTER.

After the 'mastodon' user is created, run the below command to log in.

su - mastodon

Next, download the rbenv source code via the git command below.

git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Then run the below command to install rbenv on your system.

cd ~/.rbenv && src/configure && make -C src

You'll receive the output like this after the rbenv is installed.

Next, run the below command to add the rbenv 'bin' directory to the system PATH and load rbenv every time the user logs in to the new session.

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc

Now reload your current shell by reloading the bashrc config file. Then input the 'rbenv' command on your shell and press TAB.

source ~/.bashrc
rbenv TAB

In the following screenshot, the rbenv is installed and you can now execute the rbenv command for installing Ruby.

Before installing Ruby, you need to install the rbenv plugin called 'ruby-build'. This plugin provides command-line tools that simplified Ruby installation from source, especially for UNIX-like operating systems.

Download the 'ruby-build' plugin via the git command.

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

After the 'ruby-build' plugin is added, run the below command to install Ruby v3.0.4, which is required for the current Mastodon version.

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.4

After installation is finished, you'll receive an output similar to this.

Now run the below command to set up the default Ruby version to 3.0.4. Then verify using the ruby command as below. You'll see that Ruby v3.0.4 is installed on your Debian system.

rbenv global 3.0.4
ruby --version

Lastly, you must install a bundler as your Ruby package management. Run the gem command below to install 'bundler'.

gem install bundler --no-document

At this point, you've finished the installation of Mastodon package dependencies on your system. You've installed Ruby 3.0.4 via the rbenv Ruby version manager and installed bundler, the ruby package management tool.

In the next steps, you'll set up the PostgreSQL user that will be used for the Mastodon installation.

Setting up PostgreSQL Database Server

In this step, you'll verify the PostgreSQL service to ensure that the service is enabled and running. Then, you'll create a new PostgreSQL user/role 'mastodon' via the PostgreSQL shell.

Be sure to these commands below with root user/privileges.

Before you start, run the below systemctl command utility to ensure that the PostgreSQL service is running and enabled.

sudo systemctl is-enabled postgresql
sudo systemctl status postgresql

You should receive an output similar to this.

With the PostgreSQL is running, run the below command to log in to the PostgreSQL shell.

cd /etc/postgresql
sudo -u postgres psql

After logging in to the PostgreSQL shell, run the below PostgreSQL query to create a new role/user 'mastodon'. Also, be sure to change the default password with a new strong password.

CREATE USER mastodon CREATEDB;
ALTER USER mastodon PASSWORD 'p4ssw0rd';

Next, run the below query to ensure that the new PostgreSQL user/role is created. Then input '\q' to exit from the PostgreSQL shell.

\du
\q

The below output shows you that the new PostgreSQL user/role 'mastodon' is created.

With the PostgreSQL user/role is created, you'll then ready to install Mastodon on your Debian system.

Installing Mastodon

You'll install and configure Mastodon to your Debian server in this step. You'll also install Ruby dependencies and JavaScript dependencies for Mastodon. And lastly, you'll then start configuring Mastodon for your deployment, this includes the domain configuration, database and redis configuration, SMTP configuration, and also the Mastodon admin user configuration.

Before you start, log in to the 'mastodon' user via the command below.

su - mastodon

Now download the Mastodon source code via the git command and change the branch to the latest stable version of Mastodon. At the time of this writing, the stable version of Mastodon is v4.0.2.

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

Next, run the below command to set up the deployment of Mastodon and install Ruby dependencies.

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

The installation of Mastodon Ruby dependencies will takes time. Below is the similar output you'll receive on your terminal.

After you've installed Mastodon Ruby dependencies, run the below yarn command to install JavaScript dependencies for Mastodon.

yarn install --pure-lockfile

You'll then receive an output similar to this.

With Ruby dependencies and JavaScript dependencies installed, you'll then set up your Mastodon installation.

Run the below command to set up Mastodon for the production environment.

RAILS_ENV=production bundle exec rake mastodon:setup

You'll be asked about some configurations of Mastodon.

• The Mastodon domain name? This example uses the domain 'mastodon.howtoforge.local'.
• Enable single-user mode? Input y.
• Using Docker to run Mastodon? Input n for no.
• Input the PostgreSQL user and password and ensure that you get the message 'Database configuration works!'.
• Redis configuration? leave it as default by pressing ENTER.
• Enable upload files to the cloud? Input n for no.
• Allow sending emails from localhost? Input y for yes to confirm or n for no. This depends on your environment, you can also use a third-party SMTP server.
• Save the configuration? Input y for yes.
• For the database creation. Input y to create the Mastodon database.
• Input y to compile assets and static files for the Mastodon.
• Setup admin user? Input the new admin user and email for your Mastodon installation. And you'll then get the password generated automatically to your screen.

Mastodon configuration for domain name, PostgreSQL, Redis server, and SMTP Mail server.

Mastodon generates assets and static files.

The mastodon admin user is created and the password is also generated to the terminal screen.

At this point, you've finished the installation and configuration of Mastodon on Debian 11. In the next steps, you'll set up Mastodon as a systemd service.

Running Mastodon as Systemd Service

By default, the Mastodon provides a sample of systemd service files that are available on the '/home/mastodon/live/dist/' directory.

Run the below command to copy Mastodon service files to the '/etc/systemd/system' directory.

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

Now reload the systemd manager to apply the changes on the systemd.

sudo systemctl daemon-reload

After that, start and enable Mastodon services via the systemctl command utility below.

sudo systemctl start mastodon-web mastodon-sidekiq mastodon-streaming
sudo systemctl enable mastodon-web mastodon-sidekiq mastodon-streaming

Mastodon services should now be up and running and also enabled. Verify using the below systemctl command.

sudo systemctl status mastodon-web mastodon-sidekiq mastodon-streaming

You'll receive an output similar to the following screenshots.

The mastodon-web service is running and enabled.

The mastodon-sidekiq also running and enabled.

The mastodon-streaming service also running and enabled.