Install Pleroma on Ubuntu 22.04 LTS

Published on November 23, 2022•Updated on November 21, 2023

Pleroma is a lightweight server that participates in the Fediverse. Pleroma is an alternative to the Mastodon server software. Compared to Mastodon, Pleroma does not need as much processor or RAM for a similar installation. This tutorial documents the installation steps for a Pleroma server. The server can be an individual's home instance for the Fediverse or an instance to share with friends, family, or communities of interest.

Prerequisites

A fresh Vultr Ubuntu 22.04 LTS server instance. A single-user instance will run nicely on an instance with 1 GB RAM. The hostname should be set to the fully qualified domain name (FQDN), such as pleroma.example.com used for the server. The Pleroma software and operating system files will use approximately 8.2 GB of disk space.
A non-root sudo user. Use Vultr's best practice guide to create a sudo user on Ubuntu..
A fully qualified domain name (FQDN) pointing to the server's IP address.

Examples

This tutorial uses examples:

Server hostname: pleroma
Server Fully Qualified Domain Name (FQDN): pleroma.example.com
IP address: 192.0.2.1

Initial Steps

Verify hostname and FQDN

Verify the instance's hostname is set to the hostname intended for the server.

$ hostname
pleroma

If the hostname is incorrect, follow Vultr's instructions for changing a hostname or reinstall the image with the correct hostname. Reinstalling the image to modify the hostname will completely wipe everything on the instance so this must be done before any further configuration occurs.

Set environment variables for commonly used items: This should look like export FQDN=pleroma.example.com, export EMAIL=admin@example.com, and export USER=admin

$ export FQDN=<fully qualified domain name>    
$ export EMAIL=<email address>
$ export USER=<username to use on Pleroma instance>

Verify that DNS records point at the FQDN.

$ dig +short $FQDN
192.0.2.1

The DNS PTR record that associates the server's IP address with its fully qualified domain name should be configured in the Vultr control panel.

Ensure system software is up to date and enable automatic updates

The system should run current software for optimal performance and security.

$ sudo apt update
$ sudo apt -y full-upgrade

Remove any unnecessary/outdated packages:

$ sudo apt autoremove

Enable automatic installation of software updates. (Answer "Yes" to the question about downloading and installing stable updates)

$ sudo apt-get install unattended-upgrades
$ sudo dpkg-reconfigure -plow unattended-upgrades

Install Postgres and supporting software

$ sudo apt -y install git build-essential postgresql postgresql-contrib cmake libmagic-dev

Install Elixir and Erlang

$ sudo apt -y install elixir erlang-dev erlang-nox

Install image manipulation tools

$ sudo apt -y install imagemagick ffmpeg libimage-exiftool-perl

Install Pleroma

Create a user to run the Pleroma software:

$ sudo useradd -r -s /bin/false -m -d /var/lib/pleroma -U pleroma

Create the Pleroma directory

$ sudo mkdir -p /opt/pleroma
$ sudo chown -R pleroma:pleroma /opt/pleroma

Clone the Pleroma git repository as the Pleroma user

$ sudo -Hu pleroma git clone -b stable https://git.pleroma.social/pleroma/pleroma /opt/pleroma

Change to the pleroma subdirectory

$ cd /opt/pleroma

Install Pleroma's supporting packages. Answer Yes when asked to install Hex.

$ sudo -Hu pleroma mix deps.get

Generate the pleroma configuration. This may take several minutes. Answer Yes when asked to install rebar3.

$ sudo -Hu pleroma MIX_ENV=prod mix pleroma.instance gen

The configuration program will ask a series of questions that should be answered as follows:

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

All files successfully written! Refer to the installation instructions for your platform for next steps.
Please transfer your config to the database after running database migrations. Refer to "Transfering the config to/from the database" section of the docs for more information.

Move the configuration files to their final location:

$ sudo -Hu pleroma mv config/{generated_config.exs,prod.secret.exs}

Improve security configuration

Set secure_cookie_flag to true so cookies are sent over a secure connection.

$ sudo sed -i 's/secure_cookie_flag: false/secure_cookie_flag: true/g' config/config.exs

Enable strict transport security so an attacker cannot downgrade an HTTPS connection to HTTP.

$ sudo sed -i 's/ sts: false/ sts: true/g' config/config.exs

Update ca-certificates.crt file and add it to pleroma configuration:

$ sudo update-ca-certificates --fresh
$ sudo sed -i 's,path/to/file/with/PEM/cacerts,/etc/ssl/certs/ca-certificates.crt,' config/description.exs

Create the Postgres database:

$ sudo -Hu postgres psql -f config/setup_db.psql

Run the database migration:

$ sudo -Hu pleroma MIX_ENV=prod mix ecto.migrate

Install Nginx

Nginx will act as a reverse proxy in front of Pleroma, handling the TLS and session management.

$ sudo apt -y install nginx

Stop Nginx to allow Certbot to use port 80:

$ sudo service nginx stop

Configure firewall (ufw) to allow inbound TCP connections on port 80 and 443:

$ sudo ufw allow http
$ sudo ufw allow https

Install Certbot and request TLS certificate

$ sudo apt -y install certbot
$ sudo mkdir -p /var/lib/letsencrypt/

Certbot will ask for approval of Let's Encrypt's (mandatory) terms of service and offer a subscription to an (optional) mailing list. Certbot will configure itself to refresh the TLS certificate automatically.

$ sudo certbot certonly --email $EMAIL -d $FQDN --standalone

Install Nginx configuration

$ 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

Add domain name to Nginx configuration

$ sudo sed -i "s,example.tld,$FQDN," /etc/nginx/sites-available/pleroma.nginx

Enable Nginx to start at boot time and start it immediately

$ sudo systemctl enable --now nginx.service

Install systemd service file:

$ sudo cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service

Enable Pleroma to start at boot time and start it immediately:

$ sudo systemctl enable --now pleroma.service

Create administrative Pleroma user:

$ sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new $USER $EMAIL --admin

The system will display a URL to set the password for the specified username.

Final steps

Set a password using the provided link and click on "Homepage".

Log in with the username/password just created and go to the "Administration" menu by clicking on the globe icon at the top right of the screen, then choose "Settings" on the left panel, then choose "Instance". Scroll down and modify the "Registrations open" setting to allow (the default choice) or refuse public user registrations and status posts and set the other options as appropriate. Modify the "Federating" setting to allow (default) or deny connections to other servers in the Fediverse.

Choose the "SUBMIT" button to send configuration changes to the server. The installation is complete.