docs: TLS (Caddy) - Revise advice on `tls internal` (#4305)

docs/content/config/security/ssl.md

@@ -485,6 +485,8 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
 
 !!! example
 
+    While DMS does not need a webserver to work, this workaround will provision a TLS certificate for DMS to use by adding a dummy site block to trigger cert provisioning.
+
     ```yaml title="compose.yaml"
     services:
       # Basic Caddy service to provision certs:
@@ -510,9 +512,12 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
           - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
     ```
 
+    An explicit entry in your `Caddyfile` config will have Caddy provision and renew a certificate for your DMS FQDN:
+
     ```caddyfile title="Caddyfile"
     mail.example.com {
-      tls internal {
+      # Optionally provision RSA 2048-bit certificate instead of ECDSA P-256:
+      tls {
         key_type rsa2048
       }
 
@@ -522,10 +527,12 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
     }
     ```
 
-    While DMS does not need a webserver to work, this workaround will provision a TLS certificate for DMS to use.
+    !!! info
 
-    - [`tls internal`][caddy-docs::tls-internal] will create a local self-signed cert for testing. This targets only the site-address, unlike the global `local_certs` option.
+        An explicit `tls` directive affects only the site-address block it's used in:
-    - [`key_type`][caddy-docs::key-type] can be used in the `tls` block if you need to enforce RSA as the key type for certificates provisioned. The default is currently ECDSA (P-256).
+
+        - Use [`tls internal { ... }`][caddy-docs::tls-internal] if wanting to create a local self-signed cert, which may be useful for testing. This allows opt-in to use self-signed certs unlike the global `local_certs` option.
+        - [`key_type`][caddy-docs::key-type] can be used in the `tls` block if you need to enforce RSA as the key type for certificates provisioned. The default is currently ECDSA (P-256). This may improve compatibility with legacy clients.
 
 ??? example "With `caddy-docker-proxy`"
 
@@ -558,9 +565,9 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
         labels:
           # Set your DMS FQDN here to add the site-address into the generated Caddyfile:
           caddy_0: mail.example.com
-          # Add a dummy directive is required:
+          # Adding a dummy directive is required:
           caddy_0.respond: "Hello DMS"
-          # Uncomment to make a proxy for Rspamd
+          # Uncomment to make a proxy for Rspamd:
           # caddy_1: rspamd.example.com
           # caddy_1.reverse_proxy: "{{upstreams 11334}}"
     ```
@@ -571,6 +578,23 @@ DSM-generated letsencrypt certificates get auto-renewed every three months.
 
     This can make the volume mounting for DMS to find the certificates non-deterministic, but you can [restrict provisioning to single service via the `acme_ca` setting][caddy::restrict-acme-provisioner].
 
+    ---
+
+    **NOTE:** Bind mounting a file directly instead of a directory will mount by inode. If the file is updated at renewal and this modifies the inode on the host system, then the container will still point to the old certificate.
+
+    If this happens, consider using our manual TLS type instead:
+
+    ```yaml title="compose.yaml"
+    services:
+      mailserver:
+        environment:
+          SSL_TYPE: manual
+          SSL_CERT_PATH: /srv/tls/mail.example.com/mail.example.com.crt
+          SSL_KEY_PATH: /srv/tls/mail.example.com/mail.example.com.key
+        volumes:
+          - ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/:/srv/tls/mail.example.com/:ro
+    ```
+
 ### Traefik
 
 [Traefik][traefik::github] is an open-source application proxy using the [ACME protocol][ietf::rfc::acme]. Traefik can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc.