docs: per-container Pre-Hooks and Post-Hooks

Author: buchdag

docs/Hooks.md

@@ -1,42 +1,70 @@
 ## Pre-Hooks and Post-Hooks
 
-The Pre- and Post-Hooks of [acme.sh](https://github.com/acmesh-official/acme.sh/) are available through the corresponding environment variables. This allows to trigger actions just before and after certificates are issued (see  [acme.sh documentation](https://github.com/acmesh-official/acme.sh/wiki/Using-pre-hook-post-hook-renew-hook-reloadcmd))
+The Pre- and Post-Hooks of [acme.sh](https://github.com/acmesh-official/acme.sh/) are available through the corresponding environment variables. This allows to trigger actions just before and after certificates are issued (see [acme.sh documentation](https://github.com/acmesh-official/acme.sh/wiki/Using-pre-hook-post-hook-renew-hook-reloadcmd)).
 
-#### Pre-Hook
-This command will be run before certificates are issued. For example `echo 'start'`:
+If you set `ACME_PRE_HOOK` and/or `ACME_POST_HOOK` on the **acme-companion** container, **the actions for all certificates will be the same**. If you want specific actions to be run for specific certificates, set the `ACME_PRE_HOOK` / `ACME_POST_HOOK` environment variable(s) on the proxied container(s) instead. Default (on the **acme-companion** container) and per-container `ACME_PRE_HOOK` / `ACME_POST_HOOK` environment variables aren't combined : if both default and per-container variables are set for a given proxied container, the per-container variables will take precedence over the default.
+
+If you want to run the same default hooks for most containers but not for some of them, you can set the `ACME_PRE_HOOK` / `ACME_POST_HOOK` environment variables to the Bash noop operator (ie, `ACME_PRE_HOOK=:`) on those containers.
+
+#### Pre-Hook: `ACME_PRE_HOOK`
+This command will be run before certificates are issued.
+
+For example `echo 'start'` on the **acme-companion** container (setting a default Pre-Hook):
 ```shell
 $ docker run --detach \
     --name nginx-proxy-acme \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
     --volume acme:/etc/acme.sh \
     --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
-    --env "ACME_PRE_HOOK=echo 'start'"
+    --env "ACME_PRE_HOOK=echo 'start'" \
     nginxproxy/acme-companion
 ```
 
-#### Post-Hook
-This command will be run after certificates are issued. For example `echo 'end'`:
+And on a proxied container (setting a per-container Pre-Hook):
+```shell
+$ docker run --detach \
+    --name your-proxyed-app \
+    --env "VIRTUAL_HOST=yourdomain.tld" \
+    --env "LETSENCRYPT_HOST=yourdomain.tld" \
+    --env "ACME_PRE_HOOK=echo 'start'" \
+    nginx
+```
+
+#### Post-Hook: `ACME_POST_HOOK`
+This command will be run after certificates are issued.
+
+For example `echo 'end'` on the **acme-companion** container (setting a default Post-Hook):
 ```shell
 $ docker run --detach \
     --name nginx-proxy-acme \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
     --volume acme:/etc/acme.sh \
     --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
-    --env "ACME_POST_HOOK=echo 'end'"
+    --env "ACME_POST_HOOK=echo 'end'" \
     nginxproxy/acme-companion
 ```
 
+And on a proxied container (setting a per-container Post-Hook):
+```shell
+$ docker run --detach \
+    --name your-proxyed-app \
+    --env "VIRTUAL_HOST=yourdomain.tld" \
+    --env "LETSENCRYPT_HOST=yourdomain.tld" \
+    --env "ACME_POST_HOOK=echo 'start'" \
+    nginx
+```
+
 #### Verification:
 If you want to check wether the hook-command is delivered properly to [acme.sh](https://github.com/acmesh-official/acme.sh/), you should check `/etc/acme.sh/[EMAILADDRESS]/[DOMAIN]/[DOMAIN].conf`.
 The variable `Le_PreHook` contains the Pre-Hook-Command base64 encoded.
 The variable `Le_PostHook` contains the Pre-Hook-Command base64 encoded.
 
 #### Limitations
 * The commands that can be used in the hooks are limited to the commands available inside the **acme-companion** container. `curl` and `wget` are available, therefore it is possible to communicate with tools outside the container via HTTP, allowing for complex actions to be implemented outside or in other containers.
-* The hooks are general options, therefore **the actions for all certificates are the same**.
 
 #### Use-cases
-* Change some firewall rules just for the issuing process of the certificates, so the ports 80 and/or 443 don't have to be publicly reachable at all time.
+* Changing some firewall rules just for the ACME authorization, so the ports 80 and/or 443 don't have to be publicly reachable at all time.
+* Certificate "post processing" / conversion to another format.
 * Monitoring.

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

@@ -75,6 +75,11 @@ If the ACME CA provides multiple cert chain, you can use the `ACME_PREFERRED_CHA
 
 The `LETSENCRYPT_RESTART_CONTAINER` environment variable, when set to `true` on an application container, will restart this container whenever the corresponding cert (`LETSENCRYPT_HOST`) is renewed. This is useful when certificates are directly used inside a container for other purposes than HTTPS (e.g. an FTPS server), to make sure those containers always use an up to date certificate.
 
+#### Pre-Hook and Post-Hook
+
+The `ACME_PRE_HOOK` and `ACME_POST_HOOK` let you use the [`acme.sh` Pre- and Post-Hooks feature](https://github.com/acmesh-official/acme.sh/wiki/Using-pre-hook-post-hook-renew-hook-reloadcmd) to run commands respectively before and after the container's certificate has been issued. For more information see [Pre- and Post-Hook](./Hooks.md)
+
+
 ### global (set on acme-companion container)
 
 #### Default contact address