docs: add documentation

closes dananglin/pleroma-ansible-playbook#2

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 **\<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](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
+  ```

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

examples/inventory.yml

@@ -0,0 +1,18 @@
+---
+all:
+  children:
+    pleroma:
+      hosts:
+        pleroma-01:
+          ansible_connection: ssh
+          ansible_host: <ANSIBLE_HOSTS>
+          ansible_user: <ANSIBLE_USER>
+    pleroma_database:
+      children:
+        pleroma:
+    pleroma_backend:
+      children:
+        pleroma:
+    pleroma_webserver:
+      children:
+        pleroma: