Merge pull request #550 from buchdag/default-email

Add environment variable for global default email.

Author: buchdag

README.md

@@ -65,11 +65,14 @@ $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
+    --env "[email protected]" \
     jrcs/letsencrypt-nginx-proxy-companion
 ```
 
 The host docker socket has to be bound inside this container too, this time to `/var/run/docker.sock`.
 
+Albeit **optional**, it is **recommended** to provide a valid default email address through the `DEFAULT_EMAIL` environment variable, so that Let's Encrypt can warn you about expiring certificates and allow you to recover your account.
+
 ### Step 3 - proxyed container(s)
 
 Once both **nginx-proxy** and **letsencrypt-nginx-proxy-companion** containers are up and running, start any container you want proxyed with environment variables `VIRTUAL_HOST` and `LETSENCRYPT_HOST` both set to the domain(s) your proxyed container is going to use.
@@ -83,12 +86,9 @@ $ docker run --detach \
     --name your-proxyed-app \
     --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
     --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
-    --env "[email protected]" \
     nginx
 ```
 
-Albeit **optional**, it is **recommended** to provide a valid email address through the `LETSENCRYPT_EMAIL` environment variable, so that Let's Encrypt can warn you about expiring certificates and allow you to recover your account.
-
 The containers being proxied must expose the port to be proxied, either by using the `EXPOSE` directive in their Dockerfile or by using the `--expose` flag to `docker run` or `docker create`.
 
 If the proxyed container listen on and expose another port than the default `80`, you can force **nginx-proxy** to use this port with the [`VIRTUAL_PORT`](https://github.com/jwilder/nginx-proxy#multiple-ports) environment variable.

app/letsencrypt_service

@@ -142,10 +142,13 @@ function update_certs {
 
         params_d_str=""
 
+        # Use container's LETSENCRYPT_EMAIL if set, fallback to DEFAULT_EMAIL
         email_varname="LETSENCRYPT_${cid}_EMAIL"
         email_address="${!email_varname}"
         if [[ "$email_address" != "<no value>" ]]; then
             params_d_str+=" --email $email_address"
+        elif [[ -n "${DEFAULT_EMAIL:-}" ]]; then
+            params_d_str+=" --email $DEFAULT_EMAIL"
         fi
 
         keysize_varname="LETSENCRYPT_${cid}_KEYSIZE"

docs/Advanced-usage.md

@@ -62,6 +62,7 @@ $ docker run --detach \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
     --env "NGINX_DOCKER_GEN_CONTAINER=nginx-proxy-gen" \
+    --env "[email protected]" \
     jrcs/letsencrypt-nginx-proxy-companion
 ```
 
@@ -74,7 +75,6 @@ $ docker run --detach \
     --name your-proxyed-app
     --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
     --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
-    --env "[email protected]" \
     nginx
 ```
 

docs/Basic-usage.md

@@ -35,11 +35,14 @@ $ docker run --detach \
     --name nginx-proxy-letsencrypt \
     --volumes-from nginx-proxy \
     --volume /var/run/docker.sock:/var/run/docker.sock:ro \
+    --env "[email protected]" \
     jrcs/letsencrypt-nginx-proxy-companion
 ```
 
 The host docker socket has to be bound inside this container too, this time to `/var/run/docker.sock`.
 
+Albeit **optional**, it is **recommended** to provide a valid default email address through the `DEFAULT_EMAIL` environment variable, so that Let's Encrypt can warn you about expiring certificates and allow you to recover your account.
+
 ### Step 3 - proxyed container(s)
 
 Once both **nginx-proxy** and **letsencrypt-nginx-proxy-companion** containers are up and running, start any container you want proxyed with environment variables `VIRTUAL_HOST` and `LETSENCRYPT_HOST` both set to the domain(s) your proxyed container is going to use. Multiple hosts can be separated using commas.
@@ -53,12 +56,9 @@ $ docker run --detach \
     --name your-proxyed-app
     --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
     --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
-    --env "[email protected]" \
     nginx
 ```
 
-Albeit **optional**, it is **recommended** to provide a valid email address through the `LETSENCRYPT_EMAIL` environment variable, so that Let's Encrypt can warn you about expiring certificates and allow you to recover your account.
-
 The containers being proxied must expose the port to be proxied, either by using the `EXPOSE` directive in their Dockerfile or by using the `--expose` flag to `docker run` or `docker create`.
 
 If the proxyed container listen on and expose another port than the default `80`, you can force **nginx-proxy** to use this port with the [`VIRTUAL_PORT`](https://github.com/jwilder/nginx-proxy#multiple-ports) environment variable.

docs/Let's-Encrypt-and-ACME.md

@@ -19,7 +19,29 @@ The `LETSENCRYPT_MIN_VALIDITY` environment variable can be used to set a differe
 
 #### 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.
+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. For reasons detailed below, it is **recommended** to provide a default valid contact address for all containers by setting the [`DEFAULT_EMAIL`](#default-contact-address) environment variable on the **letsencrypt_nginx_proxy_companion container**.
+
+**Please note that for each separate [ACME account](#acme-account-keys), 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.**
+
+Examples:
+
+```bash
+$ 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](https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion/issues/510#issuecomment-463256716)) and the fact that `simp_le` is silently discarding the unused addresses. Due to this, it is highly recommended to use the [`DEFAULT_EMAIL`](#default-contact-address) 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](#multiple-account-keys-per-endpoint) or [disable ACME account keys re-utilization entirely](#disable-account-keys-re-utilization).
 
 #### Private key size
 
@@ -41,6 +63,10 @@ See the [ACME account keys](#multiple-account-keys-per-endpoint) section.
 
 ### global (set on letsencrypt-nginx-proxy-companion container)
 
+#### Default contact address
+
+The `DEFAULT_EMAIL` variable must be a valid email and, when set on the **letsencrypt_nginx_proxy_companion** container, will be used as a fallback when no email address is provided using proxyed container's `LETSENCRYPT_EMAIL` environment variables.
+
 #### Private key re-utilization
 
 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.