4.7 KiB
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-backend: installs and configures the Pleroma backend.
- 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
andopenssl
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 thesecret_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
andpublicKey
fields.$ make vapid_key_pair
-
Create a password for your database and add this to the
password
field underdb
. -
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