Pleroma¶

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¶

You should’ve running a PostgreSQL in the version 9.6 or above configured with --with-uuid=e2fs

[isabell@stardust ~]$ ./configure --prefix=$HOME/opt/postgresql/ --with-python PYTHON=/usr/bin/python2 --without-readline --with-uuid=e2fs
[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 ~]$

We’re using Erlang in the version 22:

[isabell@stardust ~]$ uberspace tools version show erlang
Using 'erlang' version: '22'
[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¶

Generate configuration file¶

Note

The next step can take up to 10 minutes.

Run mix pleroma.instance gen in the pleroma directory. This will compiling 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. Additional it install 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 ~]$

Recommended minimum settings¶

Make a copy of the file ~/pleroma/config/generated_config.exs and rename it to prod.secret.exs.

[isabell@stardust ~]$ cp ~/pleroma/config/generated_config.exs ~/pleroma/config/prod.secret.exs
[isabell@stardust ~]$

For minimum privacy settings adjust your ~/pleroma/config/prod.secret.exs to disable the open registrations and set your instance private. Additional we clear the database with all posts older than 30 days to reduce space usage. Also add a database task queue timeout to avoid timeouts on the front end. Find the following block and change / add the highlighted lines:

config :pleroma, :instance,
  name: "Isabell",
  email: "isabell@uber.space",
  notify_email: "isabell@uber.space",
  limit: 5000,
  registrations_open: false,
  public: false,
  remote_post_retention: 30

config :pleroma, Pleroma.Repo,
  adapter: Ecto.Adapters.Postgres,
  username: "pleroma",
  password: "MySuperSecretPassword",
  database: "pleroma",
  hostname: "localhost",
  pool_size: 10,
  queue_target: 5000

Warning

Pleroma uses ExifTool to read and write media files metadata in the default configuration but the ExifTool binaries doesn’t exist on a default uberspace. There are two options to avoid media file upload issues.

Option A: Disable ExifTool feature¶

Note

Comment out the following line with a # in your prod.secret.exs to disable the ExifTool feature:

# config :pleroma, Pleroma.Upload, filters: [Pleroma.Upload.Filter.Exiftool]

Option B: Install ExifTool Binaries¶

Note

Checkout the ExifTool homepage for the latest release. Download, extract and copy the binaries to ~/bin:

[isabell@stardust ~]$ cd ~/tmp
[isabell@stardust tmp]$ wget https://exiftool.org/Image-ExifTool-12.14.tar.gz
[isabell@stardust tmp]$ tar -xzf Image-ExifTool-12.14.tar.gz
[isabell@stardust tmp]$ cd Image-ExifTool-12.14/
[isabell@stardust Image-ExifTool-12.14]$ cp -r exiftool lib ~/bin

Check out the Configuration Cheat Sheet for more settings.

cronjob¶

Add the following cronjob to your crontab to check daily at 04:42 for posts older than 30 days to remove.

Note

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

42 4 * * * 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
environment =
  MIX_ENV=prod

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.2.1, Uberspace 7.8.1.0

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