Ansible Playbook for Pleroma

Summary

This project was inspired by the official Pleroma OTP installation guide and contains a playbook which installs and configures Pleroma on a single Alpine Linux host. It currently contains four roles, including:

• init: merges the default configuration with the user's custom configuration.
• pleroma-postgres: installs and configures the PostgreSQL database.
• pleroma-main: installs/upgrades Pleroma and configures both the backend and frontend.
• pleroma-nginx: installs and configures Nginx, creates SSL certificates using Let's Encrypt and adds support for proving your Pleroma site with Keybase.

This project is currently used to manage my personal instance at https://fedi.dananglin.me.uk.

Additional Features

• Let's Encrypt support: This playbook creates a SSL 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.
• Custom default background: Specify an image to use as the default background of your Pleroma site.

Requirements

• A controller host running Ansible version 2.8+.
• make and openssl on the controller host which are used to generate secret values.
• A target host running Alpine Linux version 3.10.
• A (sub)domain which resolves to the IP address of the target host.

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.

Insstructions 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 priviledges.

• 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