-
Notifications
You must be signed in to change notification settings - Fork 828
Let's Encrypt and ACME
NOTE on CAA: 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. Let's Encrypt do not require that you set a CAA record on your domain, just that your DNS provider answers correctly.
NOTE on IPv6: If the domain or sub domain you want to issue certificate for has an AAAA record set, Let's Encrypt will favor challenge validation over IPv6. There is an IPv6 to IPv4 fallback in place but Let's Encrypt can't guarantee it'll work in every possible case, so bottom line is if you are not sure of both your host and your host's Docker reachability over IPv6, do not advertise an AAAA record or LE challenge validation might fail.
As described on basic usage, the LETSENCRYPT_HOST environment variables needs to be declared in each to-be-proxied application containers for which you want to enable SSL and create certificate. It most likely needs to be the same as the VIRTUAL_HOST variable and must resolve to your host (which has to be publicly reachable).
Specify multiple hosts with a comma delimiter to create multi-domain (SAN) certificates (the first domain in the list will be the base domain).
The following environment variables are optional and parametrize the way the Let's Encrypt client works.
Every hour (3600 seconds) the certificates are checked and per default every certificate that will expire in the next 30 days (90 days / 3) is renewed.
The LETSENCRYPT_MIN_VALIDITY environment variable can be used to set a different minimum validity (in seconds) for certificates. Note that the possible values are internally capped at an upper bound of 7603200 (88 days) and a lower bound of 7200 (2 hours) as a security margin, considering that the Let's Encrypt CA does only issues certificates with a lifetime of 90 days (upper bound), the rate limits imposed on certificate renewals are 5 per week (upper bound), and the fact that the certificates are checked and renewed accordingly every hour (lower bound).
The LETSENCRYPT_EMAIL environment variable must be a valid email and will be used by Let's Encrypt to warn you of impeding certificate expiration (should the automated renewal fail) and to recover an account. It is recommended to provide a valid contact address using this variable.
The LETSENCRYPT_KEYSIZE environment variable determines the size of the requested key (in bit, defaults to 4096).
The LETSENCRYPT_TEST environment variable, when set to true on a proxied application container, will create a test certificates that don't have the 5 certs/week/domain limits and are signed by an untrusted intermediate (they won't be trusted by browsers).
If you want to do this globally for all containers, set ACME_CA_URI as described in Container configuration.
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.
See the ACME account keys section.
The REUSE_PRIVATE_KEYS environment variable, when set to true on the letsencrypt-nginx-proxy-companion container, will set simp_le to reuse previously generated private key instead of generating a new one at renewal for all domains.
Reusing private keys can help if you intend to use HPKP, but please note that HPKP will be deprecated by at least one major browser (Chrome), and that it is therefore strongly discouraged to use it at all.
See the ACME account keys section.
By default the container will save the first ACME v2 account key and account registration created for each ACME v2 API endpoint used, and will reuse them for all subsequent authorization and issuance requests made to this endpoint. This behaviour is enabled by default to avoid running into Let's Encrypt account rate limits.
For instance, when using the default Let's Encrypt ACME v2 production endpoint, the container will save the first account key created for this endpoint as /etc/nginx/certs/accounts/acme-v02.api.letsencrypt.org/directory/default_key.json, the corresponding account registration as /etc/nginx/certs/accounts/acme-v02.api.letsencrypt.org/directory/default_reg.json and will reuse them for future requests made to this endpoint.
If required, you can use multiple accounts for the same ACME v2 API endpoint by using the LETSENCRYPT_ACCOUNT_ALIAS environment variable on your proxied container(s). This instruct the letsencrypt-nginx-proxy-companion container to look for an account key and an account registration named after the provided alias instead of default_key.json and default_reg.json. For example, LETSENCRYPT_ACCOUNT_ALIAS=client1 will use the key named client1_key.json and the registration named client1_reg.json in the corresponding ACME API endpoint folder for this proxied container (or will create them if they do not exist yet).
Please see the One Account or Many? paragraph on Let's Encrypt Integration Guide for additional information.
If you want to disable the account key and registration re-utilization entirely, you can set the environment variable REUSE_ACCOUNT_KEYS to false on the letsencrypt-nginx-proxy-companion container. This creates a new ACME v2 account key and account registration for each new certificate issuance. Note that this won't create new account keys / registrations for certs already issued before REUSE_ACCOUNT_KEYS is set to false. This is not recommended unless you have specific reasons to do so.