From 7331d314c422ec9b113ea3d09135355d89610824 Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Wed, 1 Mar 2023 09:45:54 +0200
Subject: [PATCH] Improve wording

---
 docs/configuring-playbook-ssl-certificates.md | 74 +++++++++++--------
 1 file changed, 42 insertions(+), 32 deletions(-)

diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md
index 859885dda..bde425bde 100644
--- a/docs/configuring-playbook-ssl-certificates.md
+++ b/docs/configuring-playbook-ssl-certificates.md
@@ -29,47 +29,57 @@ devture_traefik_config_entrypoint_web_secure_enabled: false
 
 ## Using self-signed SSL certificates
 
-To use self-signed SSL certificates, you need to disable the certResolvers and the traefik-certs-dumper tool. 
-You also need to override the providers.file setting in the Traefik configs. 
+To use self-signed SSL certificates, you need to:
 
-Create a file 'certificates.yml' in /devture-traefik/config/ with the following content:
-
-```yaml
-tls:
-  certificates:
-    - certFile: /ssl/cert.pem
-      keyFile: /ssl/privkey.pem
-  stores:
-    default:
-      defaultCertificate:
-        certFile: /ssl/cert.pem
-        keyFile: /ssl/privkey.pem
-```
-
-Place the key and your certificate in /devture-traefik/ssl/
-
-You can use the matrix-aux role for this:
-
-```yaml
-matrix_aux_file_definitions:
- - dest: /devture-traefik/ssl/privkey.pem
-   src: /path/to/privkey.pem
- - dest: /devture-traefik/ssl/cert.pem
-   src: /path/to/cert.pem
- - dest: /devture-traefik/config/certificates.yml
-   src: /path/to/certificates.yml
-```
-
-Then add the following to your vars.yml:
+- disable `certResolvers` in Traefik, so it won't attempt to retrieve SSL certificates using the default certificate resolver (using [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/))
+- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the `matrix-aux` role) or manually
+- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/)
+- put the SSL files on the server, with the help of this Ansible playbook (via the `matrix-aux` role) or manually
 
 ```yaml
+# Disable ACME / Let's Encrypt support
 devture_traefik_config_certificatesResolvers_acme_enabled: false
+
+# Unset the default certificate resolver
 devture_traefik_certResolver_primary: ''
+
+# Keep the SSL directory normally used for ACME / Let's Encrypt certificates.
+# We need to explicitly enable this, because disabling ACME support (above) automatically disables it otherwise.
 devture_traefik_ssl_dir_enabled: true
+
+# Tell Traefik to load our custom configuration file (certificates.yml).
+# The file is created below. See `matrix_aux_file_definitions`.
+# The `/config/..` path is an in-container path, not a path on the host. Do not change it!
 devture_traefik_configuration_extension_yaml: |
   providers:
     file:
       filename: /config/certificates.yml
       watch: true
-matrix_playbook_traefik_certs_dumper_role_enabled: false
+
+# Use the matrix-aux role to create our custom files on the server.
+# If you'd like to do this manually, you remove this `matrix_aux_file_definitions` variable.
+matrix_aux_file_definitions:
+  # Create the privkey.pem file on the server by
+  # uploading a file from the computer where Ansible is running.
+  - dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem"
+    src: /path/on/your/Ansible/computer/to/privkey.pem
+
+  # Create the cert.pem file on the server
+  # uploading a file from the computer where Ansible is running.
+  - dest: "{{ devture_traefik_ssl_dir_path }}/cert.pem"
+    src: /path/on/your/Ansible/computer/to/cert.pem
+
+  # Create the custom Traefik configuration.
+  # The `/ssl/..` paths below are in-container paths, not paths on the host. Do not change them!
+  - dest: "{{ devture_traefik_config_dir_path }}/certificates.yml"
+    content: |
+      tls:
+        certificates:
+          - certFile: /ssl/cert.pem
+            keyFile: /ssl/privkey.pem
+        stores:
+          default:
+            defaultCertificate:
+              certFile: /ssl/cert.pem
+              keyFile: /ssl/privkey.pem
 ```