Pleroma: same fediverse, better than Mastodon!

This step-by-step guide shows how to build and install the Pleroma back-end on a Linux server. While Mastodon is the most popular software on the Fediverse, it is not the only one, or the best. Alternative back-ends like Pleroma are more lightweight and support features like full text search for all users, or in the federated timeline. Aside from extended features like quote posts and emoji reactions, Pleroma remains fully compatible with Mastodon.

The steps have been tested on Ubuntu 20.04 and 22.04. but it should be similar for other Linux distributions. Let's get started by updating packages and installing base Pleroma dependencies:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl unzip net-tools
sudo apt install -y libncurses5 libmagic-dev libssl-dev
sudo apt install -y imagemagick ffmpeg exiftool

Install PostgreSQL with the RUM extension for faster full text search:

sudo apt install -y postgresql postgresql-contrib
apt-cache search "PostgreSQL RUM" | cut -d ' ' -f 1 | xargs sudo apt install -y
sudo systemctl restart postgresql

Create the 'pleroma' user:

sudo adduser --system --shell /bin/false --home /opt/pleroma pleroma

Create Pleroma directories:

sudo mkdir -p /var/lib/pleroma/uploads
sudo mkdir -p /var/lib/pleroma/static
sudo chown -R pleroma /var/lib/pleroma
sudo mkdir -p /etc/pleroma
sudo chown -R pleroma /etc/pleroma

Install development dependencies:

sudo apt install git cmake automake autoconf
sudo apt install libmagic-dev libncurses5-dev libssl-dev
sudo apt install build-essential elixir erlang-dev erlang-nox

Clone the Pleroma sources using a release tag (v2.4.4):

mkdir ~/git && cd ~/git
git clone -b v2.4.4 https://git.pleroma.social/pleroma/pleroma pleroma
cd pleroma

Create symlinks to Pleroma executables such that you can call 'pleroma' and 'pleroma_ctl' more easily:

sudo ln -s /opt/pleroma/bin/pleroma /usr/local/bin/pleroma
sudo ln -s /opt/pleroma/bin/pleroma_ctl /usr/local/bin/pleroma_ctl

Build Pleroma for release, install it in a temporary directory, then create a tarball:

export MIX_ENV="prod"
mix local.hex --force
mix local.rebar --force
mix deps.get --only prod
mkdir /tmp/pleroma
mix release --path /tmp/pleroma
tar -czf ~/pleroma.tar.gz -C /tmp pleroma

Extract and install the Pleroma tarball in /opt/pleroma:

sudo tar -xzf ~/pleroma.tar.gz -C /opt
sudo chown -R pleroma /opt/pleroma

Generate the Pleroma configuration file:

export MIX_ENV="prod"
sudo -Hu pleroma pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /etc/pleroma/setup_db.psql

Answer the questions when prompted:

What domain will your instance use? (e.g pleroma.soykaf.com) [] packet.social
What is the name of your instance? (e.g. The Corndog Emporium) [packet.social]
What is your admin email address? [] admin@packet.social
What email address do you want to use for sending email notifications? [admin@packet.social]
Do you want search engines to index your site? (y/n) [y]
Do you want to store the configuration in the database (allows controlling it from admin-fe)? (y/n) [n] y
What is the hostname of your database? [localhost]
What is the name of your database? [pleroma]
What is the user used to connect to your database? [pleroma]
What is the password used to connect to your database? [autogenerated]
Would you like to use RUM indices? [n] y
What port will the app listen to (leave it if you are using the default setup with nginx)? [4000]
What ip will the app listen to (leave it if you are using the default setup with nginx)? [127.0.0.1]
What directory should media uploads go in (when using the local uploader)? [/var/lib/pleroma/uploads]
What directory should custom public files be read from (custom emojis, frontend bundle overrides, robots.txt, etc.)? [/var/lib/pleroma/static]
Do you want to strip location (GPS) data from uploaded images? This requires exiftool, it was detected as not installed, please install it if you answer yes. (y/n) [n] y
Do you want to anonymize the filenames of uploads? (y/n) [n]
Do you want to deduplicate uploaded files? (y/n) [n]
Writing config to /etc/pleroma/config.exs.
Writing the postgres script to /tmp/setup_db.psql.
Writing /var/lib/pleroma/static/robots.txt.

Return to the regular user shell (type exit).

Run the database setup script:

sudo -Hu postgres psql -f /tmp/setup_db.psql

Run the following 'pleroma_ctl commands to initialize the database properly:

sudo -Hu pleroma pleroma_ctl migrate
sudo -Hu pleroma pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/

Enable and start the pleroma system service:

sudo cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
sudo systemctl enable --now pleroma.service

Make sure that the pleroma service is up and running:

$ netstat -tln | grep 4000
tcp        0      0 127.0.0.1:4000          0.0.0.0:*               LISTEN

Set up nginx with letsencrypt:

sudo apt install -y nginx certbot

Stop nginx temporarily to make TCP port 80 available to certbot:

sudo systemctl stop nginx
sudo mkdir -p /var/lib/letsencrypt

Use certbot to request your letsencrypt certificate:

sudo certbot certonly --email admin@packet.social -d packet.social --standalone

If you encounter an error, review your firewall configuration to ensure port 80 is allowed. Use --test-cert with certbot to debug such issues, otherwise letsencrypt failed validation limits may be reached.

Create a script to automatically renew certificates (sudo nano /etc/cron.daily/pleroma-cert) with the following contents:

#!/bin/sh
certbot renew --cert-name packet.social --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Make the script executable (sudo chmod +x /etc/cron.daily/pleroma-cert), and it will be launched as a daily cron job.

Copy the pleroma nginx configuration, modify it, then enable the site:

sudo cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.nginx
sudo ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
sudo sed -i 's/example.tld/packet.social/g' /etc/nginx/sites-available/pleroma.nginx

Enable and start nginx system service:

sudo systemctl enable --now nginx.service

Create a first admin user:

cd /opt/pleroma
sudo -Hu pleroma pleroma_ctl user new awakecoding admin@packet.social --admin --password Password123!

You can also create a moderator account using the --moderator command-line argument.

That's it! You can now login to your new Pleroma instance and start using it with other people on the fediverse, including Mastodon!

Special thanks to Patricia for the initial Pleroma guide I followed to get started.