How to Install Pleroma Social Network Platform on Ubuntu 20.04

Pleroma is an open-source federated social networking platform, compatible with Mastodon and other ActivityPub platforms. It is a part of the Fediverse, a federated network of instances that can communicate using a common protocol. One single account on one instance can talk to the entire Fediverse network.

This guide will show you how to create your own Pleroma instance by installing it on an Ubuntu 20.04 based server.


  • A server running Ubuntu 20.04.

  • A non-root sudo user.

  • Make sure everything is updated.

    $ sudo apt update
    $ sudo apt upgrade
  • Few packages and dependencies that you need before installing Pleroma.

    $ sudo apt install wget curl gnupg2 ca-certificates lsb-release gnupg zip libncurses5 libmagic-dev -y

Step 1 - Configure Firewall

The first step is to configure the firewall. Ubuntu comes with ufw (Uncomplicated Firewall) by default.

Check if the firewall is running.

$ sudo ufw status

You should get the following output.

Status: inactive

Allow SSH port so that the firewall doesn't break the current connection on enabling it.

$ sudo ufw allow OpenSSH

Allow HTTP and HTTPS ports as well.

$ sudo ufw allow 80
$ sudo ufw allow 443

Enable the Firewall

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Check the status of the firewall again.

$ sudo ufw status

You should see a similar output.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Step 2 - Install PostgreSQL

Add the official PostgreSQL repository to the Ubuntu sources list.

$ sudo sh -c 'echo "deb $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

Add the repository's GPG key.

$ wget --quiet -O - | sudo apt-key add -

Update the system packages list.

$ sudo apt update

Step 3 - Install Nginx

Ubuntu 20.04 ships with Nginx 18 stable version by default.

$ sudo apt install nginx

Step 4 - Install Pleroma

This guide installs Pleroma from an OTP release. The first step is to create a Pleroma user without login capabilities. It will also create the home directory for it at /opt/pleroma.

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

Switch to the Pleroma user. But first, we need to switch to the root user.

$ sudo su
$ su pleroma -s $SHELL -l

Download Pleroma to a temporary location.

$ curl "" -o /tmp/

Unzip the archive.

$ unzip /tmp/ -d /tmp/

Install Pleroma.

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

Delete the temporary files.

$ rm -rf /tmp/ /tmp/release

Switch to the root user.

$ exit

Create directories for the uploads and public files.

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

Create the directory for Pleroma configuration.

$ mkdir -p /etc/pleroma

Change the ownership of Pleroma directories to the Pleroma user.

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

Step 5 - Configure Pleroma

Switch back to the Pleroma user.

$ su pleroma -s /bin/bash -l

Run the following command to generate the configuration file for the Pleroma instance.

$ ./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql

You will be asked several questions about setting up Pleroma. If you get a warning stating that the configuration file could not be found, ignore it.

pleroma@pleroma:~$ ./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql
!!! /etc/pleroma/config.exs not found! Please ensure it exists and that PLEROMA_CONFIG_PATH is unset or points to an existing file

What domain will your instance use? (e.g []

What is the name of your instance? (e.g. The Corndog Emporium) [] Howtoforge Pleroma
What is your admin email address? [] [email protected]
What email address do you want to use for sending email notifications? [[email protected]] <Press Enter>
Do you want search engines to index your site? (y/n) [y] y
Do you want to store the configuration in the database (allows controlling it from admin-fe)? (y/n) [n] n
What is the hostname of your database? [localhost] localhost
What is the name of your database? [pleroma] pleroma
What is the user used to connect to your database? [pleroma] pleroma
What is the password used to connect to your database? [autogenerated] yourpassword
Would you like to use RUM indices? [n] n
What port will the app listen to (leave it if you are using the default setup with nginx)? [4000] <Press Enter>
What ip will the app listen to (leave it if you are using the default setup with nginx)? [] <Press Enter>
What directory should media uploads go in (when using the local uploader)? [/var/lib/pleroma/uploads] <Press Enter>
What directory should custom public files be read from (custom emojis, frontend bundle overrides, robots.txt, etc.)? [/var/lib/pleroma/static] <Press Enter>
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] n
Do you want to anonymize the filenames of uploads? (y/n) [n] n
Do you want to deduplicate uploaded files? (y/n) [n] y
Writing config to /etc/pleroma/config.exs.
Writing the postgres script to /tmp/setup_db.psql.
Writing /var/lib/pleroma/static/robots.txt.

 All files successfully written! Refer to the installation instructions for your platform for next steps.

You can choose a different set of options depending upon your requirement. Choose a strong password for your database. If you want to configure your instance from Administration Panel, select y for the question on storing the configuration in the database.

Switch to the default PostgreSQL user which was created when PostgreSQL was installed.

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

Create the database using the SQL file provided by Pleroma.

$ psql -f /tmp/setup_db.psql

Switch back to the Pleroma user.

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

Initialize the database we just created.

$ ./bin/pleroma_ctl migrate

Exit to the Root user.

$ exit

Step 6 - Install SSL using Let's Encrypt

To install an SSL certificate using Let's Encrypt, we need to download the Certbot tool.

To install Certbot, we will use the Snapd package installer. Certbot's official repository has been deprecated and Ubuntu's Certbot package is more than a year old. Snapd always carries the latest stable version of Certbot and you should use that. Fortunately, Ubuntu 20.04 comes with Snapd pre-installed.

Ensure that your version of Snapd is up to date.

$ snap install core 
$ snap refresh core

Remove any old versions of Certbot.

$ apt remove certbot

Install Certbot.

$ snap install --classic certbot

Use the following command to ensure that the Certbot command can be run by creating a symbolic link to the /usr/bin directory.

$ ln -s /snap/bin/certbot /usr/bin/certbot

Stop the Nginx service.

$ systemctl stop nginx

Generate an SSL certificate.

$ certbot certonly --standalone --preferred-challenges http -d

The above command will download a certificate to the /etc/letsencrypt/live/ directory on your server.

Create a challenge web root directory for Let's Encrypt auto-renewal.

$ mkdir -p /var/lib/letsencrypt

Create a Cron Job to renew the SSL. It will run every day to check the certificate and renew if needed. For that, first, create the file /etc/cron.daily/certbot-renew and open it for editing.

$ nano /etc/cron.daily/certbot-renew

Paste the following code.

certbot renew --cert-name --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Save the file by pressing Ctrl + X and entering Y when prompted.

Change the permissions on the task file to make it executable.

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

Step 7 - Configure Nginx

Pleroma ships with a default Nginx configuration file. Install it by moving it to the /etc/nginx/sites-available directory.

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

Replace all occurrences of example.tld with your domain.

$ sed -i 's/example\.tld/' /etc/nginx/sites-available/pleroma.conf

Open the configuration file for editing.

$ nano /etc/nginx/sites-available/pleroma.conf

Uncomment the location ~ /\.well-known/acme-challenge block. The server block of your configuration file should look like the following.

server {

    listen         80;
    listen         [::]:80;

    location ~ /\.well-known/acme-challenge {
        root /var/lib/letsencrypt/;

    location / {
        return         301 https://$server_name$request_uri;

Save the file by pressing Ctrl + X and entering Y when prompted.

Enable the Pleroma Nginx configuration by creating a symlink.

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

Enable the Nginx server to start it at boot time.

$ systemctl enable nginx.

Start the Nginx server.

$ systemctl start nginx

Install the Pleroma systemd service unit file provided in the distribution.

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

Enable and start the Pleroma service.

$ systemctl enable pleroma
$ systemctl start pleroma

It may take around 30 seconds for the Pleroma site to become available. Now, you can open in your web browser to visit Pleroma. It should look like the following.

Pleroma Homepage

Step 8 - Configure Pleroma

Create an Admin user

You can create an administrative user through the command line. Switch to the Pleroma user first.

$ su pleroma -s /bin/bash -l

Create an admin user. Replace example with your username, [email protected] with your email address and password123 with a strong password.

$ ./bin/pleroma_ctl user new example [email protected] --password password123 --admin

Switch back to the root user once you are finished.

$ exit

Changing Settings

If you selected no as an answer for storing configuration in the database, that means you cannot change settings from the Administration panel of Pleroma. To change the settings, you will need to modify the /etc/pleroma/config.exs file.

$ nano /etc/pleroma/config.exs

Once you are done editing the file, you will also need to restart the Pleroma service. You may need to wait for some time before the service is resumed.

$ systemctl restart pleroma

Updating Pleroma

For updating Pleroma, the first step is to download the new release. Run the following command to download the new release of Pleroma.

$ su pleroma -s $SHELL -lc "./bin/pleroma_ctl update"

Stop Pleroma instance.

$ systemctl stop pleroma

The next step is to migrate the database.

$ su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"

Start the Pleroma instance.

$ systemctl start pleroma

Backing up Pleroma

Stop the Pleroma service.

$ systemctl stop pleroma

Switch to the Pleroma's directory.

$ cd /opt/pleroma

Run the following command to back up the database.

$ sudo -Hu postgres pg_dump -d <pleroma_db> --format=custom -f </path/to/backup_location/pleroma.pgdump>

Copy the files pleroma.pgdump, config/prod.secret.exs, config/setup_db.sql and the uploads folder to your backup destination.

Start the Pleroma service again.

$ systemctl start pleroma

Restoring Pleroma

To restore Pleroma, you need to reinstall Pleroma and make sure the Pleroma service isn't working.

Then copy the backed-up files back to their original location.

Drop the existing database and user using the following command.

$ sudo -Hu postgres psql -c 'DROP DATABASE <pleroma_db>;';` `sudo -Hu postgres psql -c 'DROP USER <pleroma_db>;'

Restore the database schema and Pleroma Postgres role with the backed-up setup_db.sql file.

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

Next, restore the Pleroma instance's data.

$ sudo -Hu postgres pg_restore -d <pleroma_db> -v -1 </path/to/backup_location/pleroma.pgdump>

Migrate the database if there are any migrations left to be performed in case you are moving to a newer version.

$ su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"

Restart the Pleroma service.

$ systemctl restart pleroma

Generate the statistics so that Postgres can properly plan the queries.

$ sudo -Hu postgres vacuumdb --all --analyze-in-stages


This concludes our tutorial on installing the Pleroma Social Network Platform on a server powered by Ubuntu 20.04. If you have any questions or feedback, post them in the comments below.

Share this page:

2 Comment(s)