Ansible Playbook for Pleroma

Table of content

• Summary
• Requirements
• Configuration
• Secrets
• Guide to setting up and running the playbook

Summary

This project is a configurable playbook that can install, configure and customise Pleroma on an Alpine Linux host. The playbook is currently used to manage my personal instance at https://fedi.dananglin.me.uk. It currently only supports installing Pleroma on a single host but will support installing it across multipe hosts in the future.

This project was inspired by the official Pleroma OTP installation guide.

This project is developed over at https://gitlab.com/dananglin/pleroma-ansible-playbook. The master branch is mirrored over at https://github.com/dananglin/pleroma-ansible-playbook.

The project's icon (Books icon) was downloaded from Icons8.

Ansible roles

There are four roles used to install and configure your Pleroma instance:

• init: merges the default configuration with your custom configuration.
• pleroma-database: maintains the database layer by installing and configuring the PostgreSQL database server, creating the database user and creating and administrating the Pleroma database.
• pleroma-main: maintains the main layer by handling the Pleroma installation, Pleroma upgrades and the configuration of the Pleroma frontend and backend.
• pleroma-proxy: maintains the proxy layer by installing and configuring Nginx, creating the TLS certificates using Let's Encrypt, adding support for proving your Pleroma site with Keybase, etc.

Additional features

• Let's Encrypt support: This playbook creates a TLS certificate using Let's Encrypt.
• Keybase support: Pleroma does not support Keybase out of the box but you can still prove that your ownership of your Pleroma site.
• Set default background: You can specify an image to use as the default background of your Pleroma site.
• Upload custom themes: You can upload custom Pleroma themes in to your Pleroma instance.
• Set default theme: You can specify the default Pleroma theme.

Requirements

For your controller host

• The controller host should the following packages installed:
  • Ansible version 2.8+.
  • make
  • openssl

For your target Pleroma host

• The target host should be running Alpine Linux version 3.10+.
• A (sub)domain which resolves to the IP address of the target host.
• A user with sudo privileges (optional, but preferable).
• The following packages installed:
  • sudo
  • python (version 3.5 or higher)

Configuration

Here's an example configuration file that you can use as a starting point to configure your Pleroma instance. This typically goes in your host_vars directory but you can place it in your group_vars directory or even inside your playbook instead. The default configuration is located here which the init role will merge with your configuration. Any fields you configured will overwrite the default.

More documentation on the configuration will be available soon.

Secrets

Following secrets are not included in the default configuration and must be generated before running the playbook:

• secretKeyBase: This is used to configure the secret_key_base in Pleroma. This is used to sign and verify cookies.
• signingSalt: This is used to configure the signing_salt in Pleroma. This is used with the secret_key_base to generate a key for signing and verifying cookies.
• vapid key pair for web push encryption: This is a private and public key pair so that Pleroma can used VAPID to identify itself to the web push service (for notifications in the browser).
• database password: This is used to authenticate access to the Pleroma database.

Instructions on generating these can be found in the guide below. It is recommended to encrypt these secrets using Ansible Vault.

Guide to setting up and running the playbook

• Copy the example inventory file to the root of this project.

  $ cp examples/inventory.yml ./
  

• In the inventory file you've just copied change <ANSIBLE_HOSTS> to the IP address of the target host and change <ANSIBLE_USER> to the user on the target host with sudo privileges.

• Copy the example playbook file to the root of the project.

  $ cp examples/site.yml ./
  

• Copy the example host_vars directory to the root of this project. This directory contains the file used to configure your Pleroma instance. You should review and edit the configuration before running the playbook.

  $ cp -a examples/host_vars ./
  

• Generate the secret key base and add this to the to the secretKeyBase field (don't forget to uncomment this).

  $ make secret_key_base
  

• Generate the signing salt and add this to the signingSalt field.

  $ make signing_salt
  

• Generate the key pair for web push encryption and add these to privateKey and publicKey fields.

  $ make vapid_key_pair
  

• Create a password for your database and add this to the password field under db.

• Optional (but recommended): Use Ansible Vault to encrypt the generated secret values above.

• Run the playbook using one of the following commands:

  # If you're not using Ansible vault
  $ ansible-playbook -i inventory.yml site.yml
  
  # If you're using Ansible vault and want to be prompted for the password
  $ ansible-playbook -i inventory.yml site.yml --ask-vault-pass
  
  # If you're using Ansible vault and a password file
  $ ansible-playbook -i inventory.yml site.yml --vault-id /path/to/your/password-file