Setting up a Small Pleroma Server

This is a work in progress and will be updated as I get time. Initially it simply documented what I did for my own server, but now it reflects a build on a test server. I intend to refine it iteratively.

My first installation of the Pleroma server social.paladyn.org, was through a Yunohost server, which I had set up on a QEMU Virtual Machine, which runs Debian Bullseye. This worked quite well to try, but had several drawbacks, including that it shared the same external IPv4 address with several other systems, which introduced complexities.

Pleroma, Mastodon or what ?

Mastodon is the best known name in the ActivityPub Federated area, and my first venture into the Fediverse was as @JohnLines@mstdn.io – but I wanted to understand the platform well enough that I could contribute to making it more widely available – probably as part of a Small Organisation Server.

Debian has a team working on providing Social Networking for Developers, and another working on packaging. Through the Social team I am @jlines@pleroma.debian.social which steered me towards Pleroma, particularly as Pleroma and Mastodon work together.

That working together, but not being Mastodon, is important as for a protocol to be an IETF Standard it must have two independent, interoperating implementations. Diversity in implementing the Fediverse makes for a healthier ecosystem.

Yunohost

Yunohost is an all-in-one solution, which is well worth investigating if you have a system which is not already set up doing other things, but in my case I decided to migrate to running Pleroma directly on a Debian Bullseye system which was already running Nginx, but did not have much running which would conflict with Pleroma.

Pleroma from Source

The official Pleroma instructions for install on Debian have two methods, one is what they call an OTP release – where they supply a pre-built binary image for many popular computer architectures, the other is to build it from source.

As my end goal is a Debian package, I went down the build from source route. In the following instructions I have adhered to the Pleroma instructions, rather than Debian standards for file locations etc.

Picking a name and setting up DNS.

You will need a name for your Federated Social Media System. Although this document is about installing Pleroma you may want to consider a more generic name, for example setting up social.example.com, in the same way as you might use www.example.com, rather than apache.example.com to allow a future switch to nginx, or vice versa. If you set up the name pointing to your target system now then there is more chance for it to propagate before you need it. You will also be asked an admin email address later, and an address for sending email notifications. You may need to do some preparation for these too.

Preparing for the installation.

In order to make sure the target system knows the dependencies which should be installed I have started a Debian package called pleroma-installer.

pleroma-installer

Note that in these commands I have a blank line between each command. They may wrap round when shown in your browser, but should be entered as one line. I have put parts you will need to change for your system in italics.

At the moment this simply asks for dependencies, and can be downloaded from https://paladyn.org/john/tmp/pleroma-installer_0.0.1_all.deb – install it by

wget -nc https://paladyn.org/john/tmp/pleroma-installer_0.0.1_all.deb

sudo apt install  ./pleroma-installer_0.0.1_all.deb

This will install the dependencies, and apt will know that they were installed for a reason, and not try to clean them up.

The plan is to create an apt repository for this installer package to enable it to be updated by apt, however as it is an installer, not a real package this is not a high priority.

Create a user and directories

On installation the package will create a pleroma user and a directory /opt/pleroma which is the main place the files are kept. If /opt/pleroma exists it will be moved to /opt/pleroma.yyyymmddhhmm and the pleroma files will be fetched again.

There will be a warning about Federation not working until it is configured.

At present this is as far as the installer package goes, partly as the next section will have some questions to answer.

Generate the instance

cd /opt/pleroma

sudo -Hu pleroma MIX_ENV=prod mix pleroma.instance gen 

Say Y to install rebar3. You will be asked for the name and email addresses you chose above. Otherwise I used the defaults, except for answering ‘y’ to Do you want to store the configuration in the database.

The installation should complete, saying ‘All files successfully written!’

sudo -Hu pleroma mv config/{generated_config.exs,prod.secret.exs}

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

The above steps put the configuration where pleroma expects it, and do the initial database setup. As I chose the option to store the configuration in the database I did:

sudo -Hu pleroma MIX_ENV=prod mix ecto.migrate

You should see logs about lots of files being compiled.

At this stage pleroma should be installed and ready to run, start it with

sudo -Hu pleroma MIX_ENV=prod mix phx.server

You will end up with pleroma running as a background process.

Set up nginx

If you started with an empty server then the installer should have pulled nginx, but if you already had apache2 installed then it will not switch web servers on you. I have not tested pleroma behind apache2. but there is a sample apache configuration in /opt/pleroma/installation

Check if nginx is running by

systemctl status nginx

and stop it by

systemctl stop nginx

Now install an SSL certificate for your new subdomain – note that it will need to exist by this stage.

sudo certbot certonly --email myuser@example.org -d social.example.org --standalone

This can fail if some other program is using port 80 (the non SSL secured web port on your computer) – for example if or apache is running, of if your domain is mistyped, or does not exist yet.

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

Edit /etc/ngix/sites-available/pleroma.nginx to change all occurrences of sample.tld to your server name e.g. social.example.com

sudo cp /opt/pleroma/installation/pleroma.service pleroma.service

sudo systemctl enable --now pleroma.service

You should now be able to access your server at https://social.example.com/ – check here if this does not work.

Create your first user

sudo -Hu pleroma MIX_ENV=prod mix pleroma.user new myuser myuser@example.com --admin

Part of the output from the pleroma.user command will be a password reset URL – enter the link into a web browser, set your password and you should have set up a pleroma server !

Feedback on this post is welcome, either by comments on this post (note that they are moderated so will not appear instantly) or via federated social media to @jlines@pleroma.debian.social.

Troubleshooting

Pleroma has quite a number of pieces, and there are stages where the setup may run into problems. Here are some of the ones which people have encountered, together with what to do about them.

Certbot unable to set up the SSL certificate

Nginx (or apache) showing the home page, not Pleroma

If you went to the web page of the site you set up, for example https://social.example.org/ – but see a default web page then web server configuration has not taken notice of the new site you added. The first thing to do is restart nginx

systemctl restart nginx

and look again, if you see the home page still then you will need to look further.

The sites which are live can be found in /etc/ngnix/sites-enabled/ – as symbolic links to the real configurations.

You can check by

ls -l /etc/nginx/sites-enabled

You should see a line like

lrwxrwxrwx 1 root root 40 Nov 3 18:39 pleroma.nginx -> /etc/nginx/sites-available/pleroma.nginx

Nginx not running

Removing pleroma

When there is a real Debian package this should just a a matter of

apt remove pleroma

but at present it does not have an uninstall script, and what it should do to tidy up is not obvious.

Removing the database

You might want to do this in order to do a re-install cleanly

systemctl stop pleroma.service

sudo -Hu postgres psql -c 'DROP DATABASE pleroma; '

sudo -Hu postgres psql -c 'DROP USER pleroma; '

Removing the files

All the files are created under /opt/pleroma, but if you run the installer a second time it moves /opt/pleroma in order to have a clean install, but not lose anything if you want to go back, or compare configuration files.