From b4ccbf1e8f2ca9a25dbac2e471546a8dad12f9b3 Mon Sep 17 00:00:00 2001 From: Nicolas Duchon Date: Wed, 2 Mar 2022 19:28:16 +0100 Subject: [PATCH] docs: per-container Pre-Hooks and Post-Hooks --- docs/Hooks.md | 46 +++++++++++++++++++++++++++------- docs/Let's-Encrypt-and-ACME.md | 5 ++++ 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/docs/Hooks.md b/docs/Hooks.md index 34e2e0c7..53ded99b 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -1,9 +1,15 @@ ## 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 \ @@ -11,12 +17,24 @@ $ docker run --detach \ --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 \ @@ -24,10 +42,20 @@ $ docker run --detach \ --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. @@ -35,8 +63,8 @@ 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. \ No newline at end of file diff --git a/docs/Let's-Encrypt-and-ACME.md b/docs/Let's-Encrypt-and-ACME.md index 5cb59840..8633a69b 100644 --- a/docs/Let's-Encrypt-and-ACME.md +++ b/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