diff --git a/README.md b/README.md index 5ecf80b..a1d63c5 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,96 @@ -# plemora-ansible-playbook +# Ansible Playbook for Pleroma -**Description:** This playbook installs and configures Pleroma, PostgreSQL and Nginx on a single Alpine Linux host. +## Summary + +This project was inspired by the official [Pleroma OTP installation guide](https://docs.pleroma.social/otp_en.html#content) +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. + +## 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](https://www.ansible.com/) version 2.8+. +- `make` and `openssl` on the controller host which are used to generate secret values. +- A target host running [Alpine Linux](https://www.alpinelinux.org/) version 3.10. +- A (sub)domain which resolves to the IP address of the target host. + +## Configuration + +Here's an [example configuration file](./examples/host_vars/pleroma-01.yml) 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](./roles/init/defaults/main.yml) 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](https://tools.ietf.org/html/rfc8292) 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](https://docs.ansible.com/ansible/latest/user_guide/vault.html). + +## Guide to setting up and running the playbook + +- Copy the [example inventory file](examples/inventory.yml) to the root of this project. + ```bash + $ cp examples/inventory.yml ./ + ``` + +- In the inventory file you've just copied change **\** to the IP address of the target host and change **\** to the user on the target host with sudo priviledges. + +- Copy the [example playbook file](examples/site.yml) to the root of the project. + ```bash + $ cp examples/site.yml ./ + ``` + +- Copy the [example host\_vars](examples/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. + ```bash + $ 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). + ```bash + $ 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: + ```bash + # 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 + ``` diff --git a/examples/host_vars/pleroma-01.yml b/examples/host_vars/pleroma-01.yml new file mode 100644 index 0000000..ee70daf --- /dev/null +++ b/examples/host_vars/pleroma-01.yml @@ -0,0 +1,26 @@ +--- +pleroma: + config: + email: &email admin@localhost.private + host: example.com + listeningPort: 4000 + instanceName: "My Instance Name" + instanceDescription: "My Instance Description" + registrationsOpen: "false" + logLevel: warn + #secretKeyBase: + #signingSalt: + webPushEncryption: + email: *email + #privateKey: + #publicKey: + db: + name: pleroma + user: pleroma + #password: + ssl: + letsEncrypt: + enable: true + acmeAccountEmail: *email + acmeDirectory: "https://acme-v02.api.letsencrypt.org/directory" + termsAgreed: yes diff --git a/examples/inventory.yml b/examples/inventory.yml new file mode 100644 index 0000000..9182d82 --- /dev/null +++ b/examples/inventory.yml @@ -0,0 +1,18 @@ +--- +all: + children: + pleroma: + hosts: + pleroma-01: + ansible_connection: ssh + ansible_host: + ansible_user: + pleroma_database: + children: + pleroma: + pleroma_backend: + children: + pleroma: + pleroma_webserver: + children: + pleroma: diff --git a/site.yml b/examples/site.yml similarity index 100% rename from site.yml rename to examples/site.yml