Docker-letsencrypt-nginx-proxy-companion: Add global variable for default LETSENCRYPT_EMAIL

[jeroen-plug]

All of the containers I use nginx-proxy for are using the same value for LETSENCRYPT_EMAIL. It would be cool if I could set a default for this value, by setting an environment variable on the letsencrypt container.

[buchdag]

Well, this is not documented yet but I realised a few month ago that LETSENCRYPT_EMAIL does not work as it should anyway : https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion/issues/510#issuecomment-463256716

The real behaviour is that the first LETSENCRYPT_EMAIL environment variable you set will become the default address, and subsequent LETSENCRYPT_EMAIL environment variables, wether they're set or not and different or not won't have any effect, providing you use the same ACME account for all of those containers. Email addresses are by ACME account, not by certificate issuance.

I've lacked time lately to address this.

[buchdag]

I'm currently working on this feature and on a modification to the doc that explains why the base LETSENCRYPT_EMAIL feature does not work as intended, how it works in practice, and what can be done to make it work as intended.

Here is the WIP doc modification, advice would be welcome:

Contact address

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.

If you want to do this globally for all containers, set DEFAULT_EMAIL on the letsencrypt_nginx_proxy_companion container.

Please note that for each separate ACME account, only the email provided as a container environment variable at the time of this account creation will be subsequently used. If you don't provide an email address when the account is created, this account will remain without a contact address even if you provide an address in the future.

Example:

$ docker run -d nginx \
  VIRTUAL_HOST=somedomain.tld \
  LETSENCRYPT_HOST=somedomain.tld \
  [email protected]

$ docker run -d nginx \
  VIRTUAL_HOST=anotherdomain.tld \
  LETSENCRYPT_HOST=anotherdomain.tld \
  [email protected]

This will result in only the first address being used ([email protected]) and it will be used for all future certificates issued with the default ACME account.

This incorrect behaviour is due to a misunderstanding about the way ACME handled contact address(es) when the container was changed to re-use ACME account keys (more info there) and the fact that simp_le is silently discarding the unused addresses. Due to this, it is highly recommended to use the DEFAULT_EMAIL environment variable to avoid unwittingly creating ACME accounts without contact addresses.

If you need to use different contact addresses, you'll need to either use different ACME account aliases or disable ACME account keys re-utilization entirely.

[buchdag]

@jeroen-plug @linusg @almereyda @jalu14, any comment on the above ?

[jeroen-plug]

Looks clear to me.
I do notice that you recommend setting LETSENCRYPT_EMAIL in the first paragraph, and switch to recommending DEFAULT_EMAIL instead in the second last paragraph.
Maybe it's a good idea to stick with one as the recommended approach for most users, and change that in the basic usage examples as well.

[buchdag]

I do notice that you recommend setting LETSENCRYPT_EMAIL in the first paragraph, and switch to recommending DEFAULT_EMAIL instead in the second last paragraph.

Right, I did not notice that, I'll have to rephrase it.

Maybe it's a good idea to stick with one as the recommended approach for most users, and change that in the basic usage examples as well.

Agreed.

[linusg]

I agree with @jeroen-plug as well, looks good otherwise. I like the explanation at the end on what exactly is happening and why it's happening. Thanks!

[buchdag]

Done as of #550

edit: let me know if you catch any typo or error in the doc

[linusg]

Any idea when it will be released @buchdag? I can't wait to strip all the equal LETSENCRYPT_EMAIL env variables from my Docker compose file...

[buchdag]

It's been merged to master so it's already available in latest.

edit: I might make a v1.11.2 release from commit 33b7d93196d6fa977e47fd541b19a29fc9238563 soonish if no new issue arise.