Pleroma

#ActivityPub #fediverse #lang-elixir #microblogging 

Pleroma is a free, federated social networking server built on open protocols. It is compatible with GNU Social, Mastodon, and many other ActivityPub implementations.

Note

For this guide you should be familiar with the basic concepts of

Prerequisites

Web domain

Your URL needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Setup PostgreSQL

We’re using PostgreSQL in the version 13. Please refer to the PostgreSQL guide to setup your instance.

[isabell@stardust ~]$ uberspace tools version show postgresql
Using 'postgresql' version: 13
[isabell@stardust ~]$

In PostgreSQL you need a database with your username as name. Otherwise there is an error when you create the database for pleroma with the later generated script.

Warning

Please replace <username> with your Uberspace username created in PostgreSQL!

[isabell@stardust ~]$ createdb --encoding=UTF8 --owner=<username> <username>
[isabell@stardust ~]$

Install libvips

Note

As of version 2.7.0 Pleroma needs libvips to be installed in order to be compiled successfully. As Uberspace 7 does not officially support the current recommended libvips installation approach with meson, fellow Uberspace users with the help of the Pleroma community have been compiled a workaround with libvips v8.13.3 which is the last version to support installation via make.

Download libvips v8.13.3 (this exact version!), extract it and enter the directory:

[isabell@stardust ~]$ cd ~/tmp
[isabell@stardust tmp]$ wget https://github.com/libvips/libvips/releases/download/v8.13.3/vips-8.13.3.tar.gz
[isabell@stardust tmp]$ tar -zxvf vips-8.13.3.tar.gz
[isabell@stardust tmp]$ cd vips-8.13.3
[isabell@stardust vips-8.13.3]$

Run configure, make and make install (the --prefix options tells make to install to your home directory):

[isabell@stardust vips-8.13.3]$ ./configure --prefix=$HOME
[...]
[isabell@stardust vips-8.13.3]$ make
[...]
[isabell@stardust vips-8.13.3]$ make install
[...]

After running make install, which vips should return ~/bin/vips and vips --version should return vips-8.13.3-Tue Nov  1 09:09:54 UTC 2022. If not, check the output of the respective commands for errors.

Set Erlang version

We’re using Erlang in the version 25:

[isabell@stardust ~]$ uberspace tools version show erlang
Using 'erlang' version: '25'
[isabell@stardust ~]$

Installation

Download the latest stable release from source into ~/pleroma

[isabell@stardust ~]$ git clone -b stable https://git.pleroma.social/pleroma/pleroma.git
Cloning into 'pleroma'...
remote: Enumerating objects: 1130, done.
remote: Counting objects: 100% (1130/1130), done.
remote: Compressing objects: 100% (143/143), done.
remote: Total 105264 (delta 1020), reused 1080 (delta 984), pack-reused 104134
Receiving objects: 100% (105264/105264), 144.76 MiB | 4.11 MiB/s, done.
Resolving deltas: 100% (79785/79785), done.
Updating files: 100% (4920/4920), done.
[isabell@stardust ~]$

cd to the new pleroma directory and run mix deps.get to install elixir dependencies:

[isabell@stardust ~]$ cd ~/pleroma
[isabell@stardust pleroma]$ mix deps.get
!!! RUNNING IN LOCALHOST DEV MODE! !!!
FEDERATION WON'T WORK UNTIL YOU CONFIGURE A dev.secret.exs
Could not find Hex, which is needed to build dependency :phoenix
Shall I install Hex? (if running non-interactively, use "mix local.hex --force") [Yn] Y
[...]
[isabell@stardust pleroma]$

Configuration

Set Pleroma environment variables

Before generating the configuration file you have to set Pleroma environment variables temporarly to make compiling with libvips work:

[isabell@stardust ~]$ export PKG_CONFIG_PATH=$HOME/lib/pkgconfig
[isabell@stardust ~]$ export VIX_COMPILATION_MODE="PLATFORM_PROVIDED_LIBVIPS"
[isabell@stardust ~]$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/lib:$HOME/lib64

Generate configuration file

Note

The next step can take up to 10 minutes.

Run mix pleroma.instance gen in the pleroma directory. This will compile the files and asks you questions about your instance and generate a configuration file in config/generated_config.exs. Decide on your own for each point. We are using the default values.

Warning

Make sure to set the listen port to 0.0.0.0 instead of 127.0.0.1 !

[isabell@stardust ~]$ cd ~/pleroma
[isabell@stardust pleroma]$ mix pleroma.instance gen
[...]
Could not find "rebar3", which is needed to build dependency :parse_trans
I can install a local copy which is just used by Mix
Shall I install rebar3? (if running non-interactively, use "mix local.rebar --force") [Yn] Y
[...]
Generated pleroma app
What domain will your instance use? (e.g pleroma.soykaf.com) []  isabell.uber.space
What is the name of your instance? (e.g. The Corndog Emporium) [isabell.uber.space]  A Uberspace Pleroma Instance
What is your admin email address? []  isabell@uber.space
What email address do you want to use for sending email notifications? [isabell@uber.space]  isabell@uber.space
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]  MySuperSecretPassword
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]  4000
What ip will the app listen to (leave it if you are using the default setup with nginx)? [127.0.0.1]  0.0.0.0
What directory should media uploads go in (when using the local uploader)? [uploads]  uploads
What directory should custom public files be read from (custom emojis, frontend bundle overrides, robots.txt, etc.)? [instance/static/]  instance/static/
Do you want to strip location (GPS) data from uploaded images? (y/n) [y]  y
Do you want to anonymize the filenames of uploads? (y/n) [n]  n
Do you want to deduplicate uploaded files? (y/n) [n]  n
Writing config to config/generated_config.exs.
Writing the postgres script to config/setup_db.psql.
Writing instance/static/robots.txt.

All files successfully written! Refer to the installation instructions for your platform for next steps.
[isabell@stardust pleroma]$

Create new PostgreSQL user and database from file

You have a PostgreSQL file in config/setup_db.psql. This script creates the user pleroma with your password MySecretPassword you gave above and the database pleroma with the user pleroma as owner. Additionally it installs the extensions citext, pg_trgm and uuid-ossp to the database. Run the script with psql:

[isabell@stardust ~]$ psql -f ~/pleroma/config/setup_db.psql
CREATE ROLE
CREATE DATABASE
You are now connected to database "pleroma" as user "isabell".
CREATE EXTENSION
CREATE EXTENSION
CREATE EXTENSION
[isabell@stardust ~]$

cronjob

Add the following cronjob to your crontab to check daily at midnight for remote posts older than 28 days to remove.

Note

If you use the environment dev make sure to set MIX_ENV= to dev instead of prod!

@daily cd ~/pleroma && MIX_ENV=prod mix pleroma.database prune_objects --vacuum >> /dev/null

Database migration

Note

For these next steps we use pleroma in the environment prod using the file ~/pleroma/config/prod.secret.exs. If you use the environment dev make sure to set MIX_ENV= to dev instead of prod!

Run MIX_ENV=prod mix ecto.migrate in the pleroma directory to migrate the database.

[isabell@stardust ~]$ cd ~/pleroma
[isabell@stardust pleroma]$ MIX_ENV=prod mix ecto.migrate
[...]
[isabell@stardust pleroma]$

Configure web server

Note

Pleroma is running on port 4000 in the default configuration.

To access the front end you have to set a new backend. You need the domain and the port you configured earlier.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

As example for this guide:

[isabell@stardust ~]$ uberspace web backend set isabell.uber.space --http --port 4000
Set backend for isabell.uber.space/ to port 4000; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Setup daemon

Create ~/etc/services.d/pleroma.ini with the following content and make sure to replace <username> with your Uberspace username and setup your environment:

[program:pleroma]
command=/usr/bin/mix phx.server
directory=%(ENV_HOME)s/pleroma
autostart=true
autorestart=true
startsecs=60
environment =
  MIX_ENV=prod,
  LD_LIBRARY_PATH="$LD_LIBRARY_PATH:%(ENV_HOME)s/lib:%(ENV_HOME)s/lib64"

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check your configuration.

Finishing Installation

Create your first user as admin with mix pleroma.user new <nickname> <email> [option ...]:

[isabell@stardust ~]$ cd ~/pleroma
[isabell@stardust pleroma]$ MIX_ENV=prod mix pleroma.user new isabell isabell@uber.space --password MySuperSecretPassword --admin
A user will be created with the following information:
  - nickname: isabell
  - email: isabell@uber.space
  - password: MySuperSecretPassword
  - name: isabell
  - bio:
  - moderator: false
  - admin: true

Continue? [Yn] Y
[...]
[isabell@stardust pleroma]$

Updates

Note

Check the release notes regularly to stay informed about the newest version.

Stop the Pleroma service:

[isabell@stardust ~]$ supervisorctl stop pleroma
pleroma: stopped
[isabell@stardust ~]$

Run git pull in the pleroma directory to pull the latest changes from upstream. After that install new dependencies and migrate the database.

[isabell@stardust ~]$ cd ~/pleroma
[isabell@stardust pleroma]$ git pull origin stable
remote: Enumerating objects: 549, done.
remote: Counting objects: 100% (549/549), done.
remote: Compressing objects: 100% (51/51), done.
remote: Total 816 (delta 514), reused 498 (delta 498), pack-reused 267
Receiving objects: 100% (816/816), 2.42 MiB | 3.48 MiB/s, done.
Resolving deltas: 100% (591/591), completed with 158 local objects.
From https://git.pleroma.social/pleroma/pleroma
 * branch                stable     -> FETCH_HEAD
   a5ccb5b0b..f891e2b2f  stable     -> origin/stable
Updating a5ccb5b0b..f891e2b2f
Fast-forward
[...]
[isabell@stardust pleroma]$ mix deps.get
[isabell@stardust pleroma]$ MIX_ENV=prod mix ecto.migrate
[isabell@stardust pleroma]$ supervisorctl start pleroma
[isabell@stardust pleroma]$

Tested with Pleroma 2.7.0, Uberspace 7.16.0

Written by: Arian Malek <https://fetziverse.de>, custompyramidfellow