Pleroma is a free, open-source federated social network with features like Twitter. This guide explains how to install Pleroma on Debian 10 with a secure, hardened Nginx reverse proxy.
Replace all occurrences of example.com
in this guide with your domain name.
Install the dependencies required for Pleroma.
Install cURL and Unzip.
# apt-get install curl unzip
Install Nginx and Certbot.
# apt-get install nginx certbot
Install ncurses and Libmagic.
# apt-get install libncurses5 libmagic-dev
Install GnuPG.
# apt-get install gnupg
Pleroma requires the latest version of PostgreSQL from the official PostgreSQL repository.
Add the official PostgreSQL repository to the sources.list
file.
# echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" >> /etc/apt/sources.list
Add the repository's PGP key.
# wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -
Update the package index.
# apt-get update
Install PostgreSQL.
# apt-get install postgresql
This guide installs Pleroma from an OTP release, which is comparable to a binary release.
Create a Pleroma user without direct login capabilities, ensuring that Pleroma vulnerabilities cannot damage the system.
# adduser --system --shell /usr/sbin/nologin --home /opt/pleroma pleroma
Switch to the pleroma user.
# su pleroma -s /bin/bash -l
Download Pleroma to a temporary location.
$ curl "https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=amd64" -o /tmp/pleroma_amd64.zip
Unpack the archive.
$ unzip /tmp/pleroma_amd64.zip -d /tmp/
Install the Pleroma build.
$ mv /tmp/release/* /opt/pleroma
Delete the temporary files.
$ rm -rf /tmp/pleroma_amd64.zip /tmp/release
Switch to the root user.
$ exit
Create directories for uploads and public files.
# mkdir -p /var/lib/pleroma/{uploads,static}
Create a configuration directory.
# mkdir -p /etc/pleroma
Transfer ownership of the directories to the pleroma user.
# chown -R pleroma /var/lib/pleroma /etc/pleroma
Set the system locale to en_US.UTF8.
# dpkg-reconfigure locales
Select en_US.UTF8 and <Ok>. Select en_US.UTF8 as the default system locale.
Switch to the pleroma user.
# su pleroma -s /bin/bash -l
Run the instance configuration file generator. Edit the following command:
Change indexable
, instance-name
, anonymize-uploads
, and dedupe-uploads
to suit your needs. Replace example.com
and your.email@example.com
with your actual domain name and email address and password123
with a strong and secure password.
$ ./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql --domain example.com --instance-name "ExampleInstance" --admin-email "your.email@example.com" --notify-email "your.email@example.com" --dbhost localhost --dbname pleroma --dbuser pleroma --dbpass password123 --rum N --indexable Y --db-configurable N --uploads-dir /var/lib/pleroma/uploads --static-dir /var/lib/pleroma/static --listen-ip 127.0.0.1 --listen-port 4000 --strip-uploads N --anonymize-uploads N --dedupe-uploads Y
You can ignore the warning that says that the configuration file could not be found.
Switch to the postgres user.
$ exit
# su postgres -s /bin/bash -l
Create the database.
$ psql -f /tmp/setup_db.psql
Switch to the pleroma user.
$ exit
# su pleroma -s /bin/bash -l
Initialize the database.
$ ./bin/pleroma_ctl migrate
Switch to the root user.
$ exit
Nginx is the reverse proxy, and Certbot automatically requests and renews a free Let's Encrypt certificate for Nginx.
Make sure Nginx is not running.
# systemctl stop nginx.service
Request a Let's Encrypt certificate. Replace example.com
with your domain name.
# certbot certonly --standalone --preferred-challenges http -d example.com
Create a challenge webroot directory for Let's Encrypt auto-renewal.
# mkdir -p /var/lib/letsencrypt
Create a task to check the certificate each day and renew if needed.
# nano /etc/cron.daily/certbot-renew
Add the following lines.
#!/bin/sh
certbot renew --cert-name example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
Save and exit the file.
Make the task executable.
# chmod +x /etc/cron.daily/certbot-renew
Install the Pleroma provided Nginx configuration file.
# mv /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.conf
Replace all occurrences of example.tld
in the example configuration file with your domain.
# sed -i 's/example\.tld/example.com/g' /etc/nginx/sites-available/pleroma.conf
Edit the Pleroma configuration file.
# nano /etc/nginx/sites-available/pleroma.conf
Uncomment the location ~ /\.well-known/acme-challenge
block. The server
block of your configuration file should look similar to this:
server {
server_name example.com;
listen 80;
listen [::]:80;
location ~ /\.well-known/acme-challenge {
root /var/lib/letsencrypt/;
}
location / {
return 301 https://$server_name$request_uri;
}
}
Save and exit the file.
Enable the Pleroma site configuration file.
# ln -s /etc/nginx/sites-available/pleroma.conf /etc/nginx/sites-enabled/pleroma.conf
Enable Nginx to start at boot and start it.
# systemctl enable --now nginx
Install the Pleroma provided systemd service unit file.
# mv /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
Enable Pleroma to start at boot and start it.
# systemctl enable --now pleroma
It may take up to 30 seconds before your Pleroma site is available.
An admin user performs administrative tasks on your instance.
Switch to the pleroma user.
# su pleroma -s /bin/bash -l
Create an admin user. Remember to replace password123
with a strong password.
$ ./bin/pleroma_ctl user new example your.email@example.com --password password123 --admin
Switch to the root user.
$ exit
These recommended steps make Pleroma more secure than the default configuration.
Set secure_cookie_flag to true.
# sed -i 's/secure_cookie_flag: false/secure_cookie_flag: true/g' /etc/pleroma/config.exs
This option ensures that Pleroma sends the session cookie over secure connections to prevent man-in-the-middle attacks from impersonating you by stealing your session key.
Enable strict transport security.
# sed -i 's/ sts: false/ sts: true/g' /etc/pleroma/config.exs
Strict transport security enforces HTTPS so that attackers cannot steal information by downgrading your connection.
Restart Pleroma to apply the settings.
# systemctl restart pleroma
You have installed your Pleroma instance. You can access it by navigating to your domain name in a web browser. Some suggested next steps are: