From a917833d3ed586ced9ab70b48be02071946d208b Mon Sep 17 00:00:00 2001
From: Stonewall Jackson <stonewall@sacredheartsc.com>
Date: Sat, 18 Feb 2023 21:07:26 -0500
Subject: prosody: add docs

---
 roles/prosody/README.md                   |  2 +-
 roles/prosody_letsencrypt_proxy/README.md | 74 +++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 roles/prosody_letsencrypt_proxy/README.md

diff --git a/roles/prosody/README.md b/roles/prosody/README.md
index 03540f6..45a1f29 100644
--- a/roles/prosody/README.md
+++ b/roles/prosody/README.md
@@ -35,7 +35,7 @@ problem for LetsEncrypt certificates.
 
 I didn't want to deal with DNS challenges for just this one use-case, so I made
 the [prosody\_letsencrypt\_proxy](../prosody_letsencrypt_proxy) role to retrieve
-certificates from an existing webserver.
+certificates from an existing webserver. This role is pulled in as a dependency.
 
 
 Variables
diff --git a/roles/prosody_letsencrypt_proxy/README.md b/roles/prosody_letsencrypt_proxy/README.md
new file mode 100644
index 0000000..b7cc234
--- /dev/null
+++ b/roles/prosody_letsencrypt_proxy/README.md
@@ -0,0 +1,74 @@
+Prosody LetsEncrypt Proxy
+=========================
+
+Description
+-----------
+
+The `prosody_letsencrypt_proxy` role is used to copy certificates from your
+webserver to your XMPP server.
+
+Because XMPP clients require certificates matching the bare JID domain, it's
+difficult to acquire LetsEncrypt certificates unless your XMPP and web server
+are on the same host.
+
+This role has two modes: `master` and `slave`.
+
+The `master` role should be run on your domain's webserver. Certificates for
+retrieved from LetsEncrypt via Certbot, and placed in a special `sftp`-accessible
+location.
+
+The `slave` role should be run on your XMPP host. It periodically scrapes the
+new certificates from the `master`, and reloads Prosody if necessary.
+
+
+Variables
+---------
+
+This role **accepts** the following variables:
+
+Variable                 | Default                | Description
+-------------------------|------------------------|------------
+`prosody_le_role`        | `slave`                | Either `master` or `slave`
+`prosody_le_domains`     | `{{ prosody_vhosts }}` | XMPP domains
+`prosody_le_proxy_host`  | &nbsp;                 | Host to retrieve certificates from
+`prosody_le_ssh_privkey` | &nbsp;                 | SSH private key for SFTP
+`prosody_le_ssh_pubkey`  | &nbsp;                 | SSH public key for SFTP
+
+Usage
+-----
+
+Example playbook:
+
+````yaml
+- name: configure webserver
+  hosts: www1
+  roles:
+    - role: apache_vhost
+      apache_server_name: www.example.com
+      apache_server_aliases: [example.com]
+      apache_canonical_hostname: www.example.com
+      apache_document_root: /var/www/www.example.com
+      apache_letsencrypt: yes
+
+    - role: prosody_letsencrypt_proxy
+      vars:
+        prosody_le_role: master
+        prosdy_le_domains:
+          - example.com
+        prosody_le_pubkey: |
+          -----BEGIN OPENSSH PUBLIC KEY-----
+          AAAAAAAAetc
+
+- name: configure prosody
+  hosts: xmpp_servers
+  roles:
+    - role: prosody
+      vars:
+        prosody_vhosts:
+          - example.com
+        prosody_le_role: slave
+        prosdy_le_proxy_host: www1
+        prosody_ssh_privkey: |
+          -----BEGIN OPENSSH PRIVATE KEY-----
+          AAAAAAAAetc
+````
-- 
cgit