docs: DNS-01 challenge support

Author: buchdag

README.md

@@ -10,20 +10,23 @@ It handles the automated creation, renewal and use of SSL certificates for proxi
 
 ### Features:
 * Automated creation/renewal of Let's Encrypt (or other ACME CAs) certificates using [**acme.sh**](https://github.com/acmesh-official/acme.sh).
-* Let's Encrypt / ACME domain validation through `http-01` challenge only.
+* Let's Encrypt / ACME domain validation through `HTTP-01` (by default) or [`DNS-01`](https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md#dns-01-acme-challenge) challenge.
 * Automated update and reload of nginx config on certificate creation/renewal.
 * Support creation of [Multi-Domain (SAN) Certificates](https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md#multi-domains-certificates).
 * Creation of a strong [RFC7919 Diffie-Hellman Group](https://datatracker.ietf.org/doc/html/rfc7919#appendix-A) at startup.
 * Work with all versions of docker.
 
-### Requirements:
+### HTTP-01 challenge requirements:
 * Your host **must** be publicly reachable on **both** port [`80`](https://letsencrypt.org/docs/allow-port-80/) and [`443`](https://github.com/nginx-proxy/acme-companion/discussions/873#discussioncomment-1410225).
-* Check your firewall rules and [**do not attempt to block port `80`**](https://letsencrypt.org/docs/allow-port-80/) as that will prevent `http-01` challenges from completing.
+* Check your firewall rules and [**do not attempt to block port `80`**](https://letsencrypt.org/docs/allow-port-80/) as that will prevent `HTTP-01` challenges from completing.
 * For the same reason, you can't use nginx-proxy's [`HTTPS_METHOD=nohttp`](https://github.com/nginx-proxy/nginx-proxy#how-ssl-support-works).
 * The (sub)domains you want to issue certificates for must correctly resolve to the host.
-* Your DNS provider must [answer correctly to CAA record requests](https://letsencrypt.org/docs/caa/).
 * If your (sub)domains have AAAA records set, the host must be publicly reachable over IPv6 on port `80` and `443`.
 
+If you can't meet these requirements, you can use the `DNS-01` challenge instead. Please refer to the [documentation](./docs/Let's-Encrypt-and-ACME.md#dns-01-acme-challenge) for more information.
+
+In addition to the above, please ensure that your DNS provider answers correctly to CAA record requests. [If your DNS provider answer with an error, Let's Encrypt won't issue a certificate for your domain](https://letsencrypt.org/docs/caa/). Let's Encrypt do not require that you set a CAA record on your domain, just that your DNS provider answers correctly.
+
 ![schema](https://github.com/nginx-proxy/acme-companion/blob/main/schema.png)
 
 ## Basic usage (with the nginx-proxy container)

docs/Basic-usage.md

@@ -3,7 +3,7 @@
 Two writable volumes must be declared on the **nginx-proxy** container so that they can be shared with the **acme-companion** container:
 
 * `/etc/nginx/certs` to store certificates and private keys (readonly for the **nginx-proxy** container).
-* `/usr/share/nginx/html` to write `http-01` challenge files.
+* `/usr/share/nginx/html` to write `HTTP-01` challenge files.
 
 Additionally, a fourth volume must be declared on the **acme-companion** container to store `acme.sh` configuration and state: `/etc/acme.sh`.
 

docs/Let's-Encrypt-and-ACME.md

@@ -10,6 +10,42 @@ The following environment variables are optional and parametrize the way the Let
 
 ### per proxyed container
 
+#### DNS-01 ACME challenge
+
+In order to switch to the DNS-01 ACME challenge, set the `ACME_CHALLENGE` environment variable to `DNS-01` on your proxied container. This will also require you to set the `ACMESH_DNS_API_CONFIG` environment variable to a JSON or YAML string containing the configuration for the DNS provider you are using. Inside the JSON or YAML string, the `DNS_API` property is always required and should be set to the name of the [acme.sh DNS API](https://github.com/acmesh-official/acme.sh/tree/3.0.7/dnsapi) you want to use.
+
+The other properties required will depend on the DNS provider you are using. For more information on the required properties for each DNS provider, please refer to the [acme.sh documentation](https://github.com/acmesh-official/acme.sh/wiki/dnsapi) (please keep in mind that nginxproxy/acme-companion is using a fixed version of acme.sh, so the documentation might include DNS providers that are not yet available in the version used by this image).
+
+Example using the [Gandi Live DNS API](https://github.com/acmesh-official/acme.sh/blob/3.0.7/dnsapi/dns_gandi_livedns.sh):
+```console
+docker run --detach \
+    --name your-proxyed-app \
+    --env "VIRTUAL_HOST=yourdomain.tld" \
+    --env "LETSENCRYPT_HOST=yourdomain.tld" \
+    --env "ACME_CHALLENGE=DNS-01" \
+    --env "ACMESH_DNS_API_CONFIG={'DNS_API': 'dns_gandi_livedns', 'GANDI_LIVEDNS_KEY': 'yourApiKey'}" \
+    nginx
+```
+
+Same example on a Docker compose file:
+```yaml
+services:
+  # [...]
+    
+  app:
+    image: nginx
+    container_name: your-proxyed-app
+    environment:
+      VIRTUAL_HOST: yourdomain.tld
+      LETSENCRYPT_HOST: yourdomain.tld
+      ACME_CHALLENGE: DNS-01
+      ACMESH_DNS_API_CONFIG: |-
+        DNS_API: dns_gandi_livedns
+        GANDI_LIVEDNS_KEY: yourApiKey
+```
+
+If you experience issues with the DNS-01 ACME challenge, please try to get it working outside of the container before opening an issue. If you can't get it working outside of the container, please seek support on the [acme.sh repository](https://github.com/acmesh-official).
+
 #### Multi-domains certificates
 
 Specify multiple hosts with a comma delimiter to create multi-domains ([SAN](https://www.digicert.com/subject-alternative-name.htm)) certificates (the first domain in the list will be the base domain).