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 Rcs 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.comused 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 Rcs'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 Rcs'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 Rcs 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.
Further reading
More information about administrating a Pleroma server is available in the official documentation.
It's essential to read the "Hardening your instance" section of the documentation for instructions to keep the Pleroma instance secure.
