more config documentation

- Added table of contents.
- Updated summary section.
- Added 'Ansible Roles' and Additional
features as subsections of summary.

README.md

@@ -1,30 +1,59 @@
 # Ansible Playbook for Pleroma
 
+## Table of content
+
+- [Summary](#summary)
+  - [Ansible roles](#ansible-roles)
+  - [Additional features](#additional-features)
+- [Requirements](#requirements)
+- [Configuration](#configuration)
+- [Secrets](#secrets)
+- [Guide to setting up and running the playbook](#guide-to-setting-up-and-running-the-playbook)
+
 ## 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:
+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.
 
-- **init:** merges the default configuration with the user's custom configuration.
-- **pleroma-postgres:** installs and configures the PostgreSQL database.
+This project was inspired by the official [Pleroma OTP installation guide](https://docs.pleroma.social/otp_en.html#content).
+
+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.
+
+### Ansible roles
+
+There are four roles used to install and configure Pleroma including:
+
+- **init:** merges the default configuration with your custom configuration.
+- **pleroma-postgres:** installs and configures the Pleroma 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
 
-## Additional Features
-
-- **Let's Encrypt support:** This playbook creates a SSL certificate using Let's Encrypt.
+- **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.
-- **Custom default background:** Specify an image to use as the default background 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
 
-- 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.
+### For your controller host
+
+- The controller host should the following packages installed:
+  - [Ansible](https://www.ansible.com/) version 2.8+.
+  - make
+  - openssl
+
+### For your target Pleroma host
+
+- The target host should be running [Alpine Linux](https://www.alpinelinux.org/) 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
 
@@ -44,7 +73,7 @@ Following secrets are not included in the default configuration and must be gene
 - **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.
+Instructions 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
@@ -54,7 +83,7 @@ It is recommended to encrypt these secrets using [Ansible Vault](https://docs.an
   $ 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.
+- 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](examples/site.yml) to the root of the project.
   ```bash

examples/host_vars/pleroma-01.yml

@@ -1,26 +1,194 @@
 ---
+# TODO: In init role fail playbook if secrets are empty
 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:
+    # field name - pleroma.config.email
+    # description -
+    #   The email address of the instance administrator (you).
+    #   This should be your personal or organisational email.
+    # default value - admin@localhost
+    email: &email admin@localhost
+
+    # field name - pleroma.config.host
+    # description - The sub(domain) of your Pleroma instance.
+    # default value - pleroma.localhost
+    host: pleroma.example.com
+
+    # field name - pleroma.config.notifyEmail
+    # description - The email used for notifications.
+    # default value - no_reply@pleroma.localhost
+    #notifyEmail: no_reply@pleroma.example.com
+
+    # field name - pleroma.config.listeningPort
+    # description - The port number that Pleroma will bind to.
+    # default value - 4000
+    #listeningPort: 4000
+
+    # field name - pleroma.config.instanceName
+    # description - The name of your Pleroma instance.
+    # default value - "Ansible Pleroma"
+    instanceName: "My Instance's Name"
+
+    # field name - pleroma.config.instanceDescription
+    # description - The description of your Pleroma instance.
+    # default value - "A new single instance of Pleroma"
+    instanceDescription: "My Instance's Description"
+
+    # field name - pleroma.config.characterLimit
+    # description - The character limit for each post.
+    # default value - 5000
+    #characterLimit: 5000
+
+    # field name - pleroma.config.registrationsOpen
+    # description - If set to "true" this allows anyone to register on your instance.
+    # default value - "false"
+    #registrationsOpen: "false"
+
+    # TODO: This needs to be updated
+    # field name - pleroma.config.
+    # description -
+    # default value -
+    #dynamicConfiguration: "false"
+
+    # field name - pleroma.config.healthCheck
+    # description - Show system data at /api/pleroma/healthcheck if set to "true".
+    # default value - "false"
+    #healthCheck: "false"
+
+    # field name - pleroma.config.remotePostRetentionDays
+    # description - The default amount of days to retain remote posts when pruning the database.
+    # default value - 90
+    #remotePostRetentionDays: 90
+
+    # field name - pleroma.config.logLevel
+    # description - Sets the log level of the Pleroma application.
+    # default value - info
+    #logLevel: info
+
+    # field name - pleroma.config.federating
+    # description - Enable federation with other instances if set to "true".
+    # default value - "true"
+    #federating: "true"
+
+    # field name - pleroma.config.chatEnabled
+    # description - Enable the chat window if set to "true".
+    # default value - "true"
+    #chatEnabled: "true"
+
+    # field name - pleroma.config.secretKeyBase
+    # description -
+    #   This is used to configure the secret_key_base in Pleroma.
+    #   It is used to sign and verify cookies.
+    #   To generate this run 'make secret_key_base'
+    #   The playbook will fail if this field is empty.
+    secretKeyBase:
+
+    # field name - pleroma.config.signingSalt
+    # description -
+    #   This is used to configure the signing_salt in Pleroma.
+    #   It is used with the secret_key_base to generate a key for signing and verifying cookies.
+    #   To generate this run 'make signing_salt'
+    #   The playbook will fail if this field is empty.
+    signingSalt:
+
+    # This section configures the... TODO
+    mrf:
+      simplePolicy:
+        #reject: []
+        #federatedTimelineRemoval: []
+        #mediaRemoval: []
+        #mediaNsfw: []
+        #reportRemoval: []
+
+    # This section configures the Pleroma frontend.
+    frontend:
+      # field name - pleroma.config.frontend.background
+      # default value - This field is empty by default
+      # description -
+      #   The path on the Ansible controller to the image
+      #   that will be uploaded to your Pleroma instance and
+      #   used as the default background image.
+      #background: /path/to/your/background/image
+
+      themes:
+        # field name - pleroma.config.frontend.themes.custom
+        # default value - An empty list
+        # description - A list of names and corresponding paths of your custom themes
+        #custom:
+        #- name: custom-theme-1
+        #  path: /file/path/to/custom/theme1
+        #- name: custom-theme-2
+        #  path: /file/path/to/custom/theme2
+
+        # field name - pleroma.config.frontend.themes.default
+        # default value - pleroma-dark
+        # description -
+        #  The default theme for your instance.
+        #  You can specify one of the default themes or even
+        #  one of your custom theme.
+        #default: custom-theme-1
+
     webPushEncryption:
+      # field name - pleroma.config.webPushEncryption.email
+      # description - 
       email: *email
-      #privateKey:
-      #publicKey:
+
+      # field name - pleroma.config.webPushEncryption.privateKey
+      # description - 
+      #   This is the private key to enable browser notifications using VAPID.
+      #   To generate this run 'make vapid_private_key'
+      #   The playbook will fail if this field is empty.
+      privateKey:
+
+      # field name - pleroma.config.webPushEncryption.publicKey
+      # description - 
+      #   The playbook will fail if this field is empty.
+      publicKey:
     db:
-      name: pleroma
-      user: pleroma
-      #password:
+      # field name - pleroma.config.db.password
+      # description -
+      #   The password to the Pleroma database.
+      #   The playbook will fail if this field is empty.
+      password:
+
+      # field name - pleroma.config.db.name
+      # description - The name of the Pleroma database.
+      # default value - pleroma_db
+      #name: pleroma_db
+
+      # field name - pleroma.config.db.user
+      # description - The name of the database user.
+      # default value - pleroma
+      #user: pleroma
+
+      # field name - pleroma.config.db.connLimit
+      # description - The number of allowed concurrent connections to the database.
+      # default value - 15
+      #connLimit: 15
   ssl:
+    #csr:
+    #  countryName: ""
+    #  emailAddress: "{{ pleroma.config.email }}"
+    #  localityName: ""
+    #  organizationName: ""
+    #  organizationUnitName: ""
+    #  stateOrProvinceName: ""
     letsEncrypt:
-      enable: true
-      acmeAccountEmail: *email
-      acmeDirectory: "https://acme-v02.api.letsencrypt.org/directory"
-      termsAgreed: yes
+      enable: false
+      #acmeAccountEmail: *email
+      #acmeDirectory: "https://acme-v02.api.letsencrypt.org/directory"
+      #termsAgreed: yes
+      #validateCerts: true
+  keybase:
+    # field name - pleroma.keybase.enable
+    # default value - false
+    # description -
+    #   If set to true the playbook will upload your keybase text file and
+    #   configure Nginx in order to prove your Keybase identity against your
+    #   Pleroma instance.
+    enable: false
+    proof:
+      # field name - pleroma.keybase.proof.filepath
+      # default value - ${HOME}/keybase.txt
+      # description - The file path to your keybase text file on your Ansible controller.
+      #filepath: "{{ lookup('env','HOME') }}/keybase.txt"

roles/init/defaults/main.yml

@@ -2,7 +2,7 @@
 pleroma_defaults:
   config:
     email: admin@localhost
-    notifyEmail: no_reply@{{ pleroma.config.host }}
+    notifyEmail: no_reply@pleroma.localhost
     host: pleroma.localhost
     listeningPort: 4000
     instanceName: "Ansible Pleroma"
@@ -10,7 +10,7 @@ pleroma_defaults:
     characterLimit: 5000
     registrationsOpen: "false"
     dynamicConfiguration: "false"
-    healthCheck: "true"
+    healthCheck: "false"
     remotePostRetentionDays: 90
     logLevel: info
     federating: "true"