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.
Prerequisites
-
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 http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
Add the repository’s GPG key.
$ wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | 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 "https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=amd64" -o /tmp/pleroma_amd64.zip
Unzip the archive.
$ unzip /tmp/pleroma_amd64.zip -d /tmp/
Install Pleroma.
$ 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 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.
[email protected]:~$ ./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 pleroma.soykaf.com) [] example.com
What is the name of your instance? (e.g. The Corndog Emporium) [nspeaks.com] Howtoforge Pleroma
What is your admin email address? [] [email protected]
What email address do you want to use for sending email notifications? [[email protected]]
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]
What ip will the app listen to (leave it if you are using the default setup with nginx)? [127.0.0.1]
What directory should media uploads go in (when using the local uploader)? [/var/lib/pleroma/uploads]
What directory should custom public files be read from (custom emojis, frontend bundle overrides, robots.txt, etc.)? [/var/lib/pleroma/static]
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 example.com
The above command will download a certificate to the /etc/letsencrypt/live/example.com 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.
#!/bin/sh
certbot renew --cert-name example.com --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/example.com/g' /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 {
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 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 https://example.com in your web browser to visit Pleroma. It should look like the following.
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 --format=custom -f
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 ;';` `sudo -Hu postgres psql -c 'DROP USER ;'
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 -v -1
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
Conclusion
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.
