-
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.
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 proxyed 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).
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 account key created for each ACME API endpoint used, and will reuse it for all subsequent authorization and issuance requests made to this endpoint. This behavior is enabled by default to avoid running into Let's Encrypt account rate limits.
For instance, when using the default Let's Encrypt production endpoint, the container will save the first account key created for this endpoint as /etc/nginx/certs/accounts/acme-v01.api.letsencrypt.org/directory/default.json and will reuse it for future requests made to this endpoint.
If required, you can use multiple accounts for the same ACME API endpoint by using the LETSENCRYPT_ACCOUNT_ALIAS environment variable on your proxyed container. This instruct the letsencrypt-nginx-proxy-companion container to look for an account key named after the provided alias instead of default.json. For example, LETSENCRYPT_ACCOUNT_ALIAS=client1 will use the key named client1.json in the corresponding ACME API endpoint folder for this proxyed container (or will create it if it does not exists 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 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 registration with a corresponding account key for each new certificate issuance. Note that this won't create new account keys for certs already issued before REUSE_ACCOUNT_KEYS is set to false. This is not recommended unless you have specific reasons to do so.