Knowledgebase

Introduction

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.

Prerequisites

• A fully updated Rcs Debian 10 VPS instance, with at least one vCPU and one GB RAM.
• A domain name that resolves to the IP address of your VPS.

Replace all occurrences of example.com in this guide with your domain name.

1. Install Dependencies

Install the dependencies required for Pleroma.

1. Install cURL and Unzip.

    # apt-get install curl unzip

2. Install Nginx and Certbot.

    # apt-get install nginx certbot

3. Install ncurses and Libmagic.

    # apt-get install libncurses5 libmagic-dev

4. Install GnuPG.

    # apt-get install gnupg

2. Install PostgreSQL

Pleroma requires the latest version of PostgreSQL from the official PostgreSQL repository.

1. 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

2. Add the repository's PGP key.

    # wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | apt-key add -

3. Update the package index.

    # apt-get update

4. Install PostgreSQL.

    # apt-get install postgresql

3. Install Pleroma

This guide installs Pleroma from an OTP release, which is comparable to a binary release.

1. 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

2. Switch to the pleroma user.

    # su pleroma -s /bin/bash -l

3. 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

4. Unpack the archive.

    $ unzip /tmp/pleroma_amd64.zip -d /tmp/

5. Install the Pleroma build.

    $ mv /tmp/release/* /opt/pleroma

6. Delete the temporary files.

    $ rm -rf /tmp/pleroma_amd64.zip /tmp/release

7. Switch to the root user.

    $ exit

8. Create directories for uploads and public files.

    # mkdir -p /var/lib/pleroma/{uploads,static}

9. Create a configuration directory.

    # mkdir -p /etc/pleroma

10. Transfer ownership of the directories to the pleroma user.

    # chown -R pleroma /var/lib/pleroma /etc/pleroma

4. Configure Pleroma

1. 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.

2. Switch to the pleroma user.

    # su pleroma -s /bin/bash -l

3. 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.

4. Switch to the postgres user.

    $ exit
    # su postgres -s /bin/bash -l

5. Create the database.

    $ psql -f /tmp/setup_db.psql

6. Switch to the pleroma user.

    $ exit
    # su pleroma -s /bin/bash -l

7. Initialize the database.

    $ ./bin/pleroma_ctl migrate

8. Switch to the root user.

    $ exit

5. Configure Nginx and Certbot

Nginx is the reverse proxy, and Certbot automatically requests and renews a free Let's Encrypt certificate for Nginx.

1. Make sure Nginx is not running.

    # systemctl stop nginx.service

2. Request a Let's Encrypt certificate. Replace example.com with your domain name.

    # certbot certonly --standalone --preferred-challenges http -d example.com

3. Create a challenge webroot directory for Let's Encrypt auto-renewal.

    # mkdir -p /var/lib/letsencrypt

4. 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.

5. Make the task executable.

    # chmod +x /etc/cron.daily/certbot-renew

6. Install the Pleroma provided Nginx configuration file.

    # mv /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.conf

7. 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

8. 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.

9. Enable the Pleroma site configuration file.

    # ln -s /etc/nginx/sites-available/pleroma.conf /etc/nginx/sites-enabled/pleroma.conf

10. Enable Nginx to start at boot and start it.

    # systemctl enable --now nginx

11. Install the Pleroma provided systemd service unit file.

    # mv /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service

12. 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.

6. Create an admin User

An admin user performs administrative tasks on your instance.

1. Switch to the pleroma user.

    # su pleroma -s /bin/bash -l

2. 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

3. Switch to the root user.

    $ exit

Harden Pleroma

These recommended steps make Pleroma more secure than the default configuration.

1. 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.

2. 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.

3. Restart Pleroma to apply the settings.

    # systemctl restart pleroma

Conclusion

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:

• Invite your friends to your instance or find new ones on other instances.
• Customize your instance using the Pleroma Configuration Cheatsheet.
• To access your Pleroma instance on the go, download one of the Pleroma clients for mobile devices.