mirror/docker-letsencrypt-nginx-proxy-companion
1
0
Fork 0
mirror of https://github.com/nginx-proxy/docker-letsencrypt-nginx-proxy-companion synced 2024-11-22 16:32:48 +01:00
Code Issues Releases Activity

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

Browse Source
This commit is contained in:
Nicolas Duchon 2022-03-02 19:28:16 +01:00
parent 16f7e198df
commit b4ccbf1e8f
No known key found for this signature in database
GPG Key ID: EA3151C66A4D79E7
2 changed files with 42 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/Hooks.md
View File

@ -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.

5
docs/Let's-Encrypt-and-ACME.md
View File

@ -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