docker-letsencrypt-nginx-proxy-companion/docs/Container-configuration.md

## Optional container environment variables for custom configuration.

* `ACME_CA_URI` - Directory URI for the CA ACME API endpoint (defaults to ``https://acme-v02.api.letsencrypt.org/directory``).

If you set this environment variable value to `https://acme-staging-v02.api.letsencrypt.org/directory` the container will obtain its certificates from Let's Encrypt test API endpoint that don't have the [5 certs/week/domain limit](https://letsencrypt.org/docs/rate-limits/) (but are not trusted by browsers).

For example

```bash
$ docker run --detach \
    --name nginx-proxy-acme \
    --volumes-from nginx-proxy \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro \
    --volume certs:/etc/nginx/certs:rw \
    --volume acme:/etc/acme.sh \
    --env "ACME_CA_URI=https://acme-staging-v02.api.letsencrypt.org/directory" \
    nginxproxy/acme-companion
```
You can also create test certificates per container (see [Test certificates](./Let's-Encrypt-and-ACME.md#test-certificates))

* `DEBUG` - Set it to `1` to enable debugging of the entrypoint script and generation of LetsEncrypt certificates, which could help you pinpoint any configuration issues. When enabled, `acme.sh`'s own detailed log is also sent to the container output (visible through `docker logs`) instead of being discarded, which is especially useful for diagnosing DNS-01 challenge failures.

* `RENEW_PRIVATE_KEYS` - Set it to `false` to make `acme.sh` reuse previously generated private key for each certificate instead of creating a new one on certificate renewal. Reusing private keys can help if you intend to use [HPKP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning), but please note that HPKP has been deprecated by Google's Chrome and that it is therefore strongly discouraged to use it at all. This can also be set per proxied container by setting `ACME_RENEW_PRIVATE_KEYS` on that container, which overrides the global value for its certificate (e.g. to keep a stable key for a DANE/TLSA mail certificate while still rotating keys elsewhere).

* `DHPARAM_BITS` - Change the key size of the RFC7919 Diffie-Hellman group used by the container from the default value of 4096 bits. Supported values are `2048`, `3072` and `4096`. The DH group file will be located in the container at `/etc/nginx/certs/dhparam.pem`. Mounting a different `dhparam.pem` file at that location will override the RFC7919 group creation by the acme-companion container. **COMPATIBILITY WARNING**: some older clients (like Java 6 and 7) do not support DH keys with over 1024 bits. In order to support these clients, you must provide your own `dhparam.pem`.

* `DHPARAM_SKIP` - Set it to `true` to disable the Diffie-Hellman group creation by the container entirely.

* `ACME_CA_BUNDLE` - This variable changes the trusted root CA used by `acme.sh`, from the default Alpine trust store to the CA bundle file located at the provided path (inside the container). This can be useful if you are running your own ACME CA.

* `CERTS_UPDATE_INTERVAL` - 3600 seconds by default, this defines how often the container will check if the certificates require update.

* `ACME_PRE_HOOK` - The provided command will be run before every certificate issuance. The action is limited to the commands available inside the **acme-companion** container. For example `--env "ACME_PRE_HOOK=echo 'start'"`. For more information see [Pre- and Post-Hook](./Hooks.md)

* `ACME_POST_HOOK` - The provided command will be run after every certificate issuance. The action is limited to the commands available inside the **acme-companion** container. For example `--env "ACME_POST_HOOK=echo 'end'"`. For more information see [Pre- and Post-Hook](./Hooks.md)

* `ACME_RENEW_AFTER` - 60 days by default, this defines the number of days between certificate renewals attempts. For certificates issued by certain Certificate Authorities, such as Buypass, which have a lifespan of 180 days, it may be advisable to initiate the renewal process on day 150 rather than the default day 60. See [BuyPass.com CA](https://github.com/acmesh-official/acme.sh/wiki/BuyPass.com-CA) for more detail. This can also be set per-container (see [Certificate renewal timing](./Let's-Encrypt-and-ACME.md#certificate-renewal-timing)).

* `DEFAULT_RENEW` - **DEPRECATED**: This variable is deprecated and replaced by `ACME_RENEW_AFTER`. It still works for backward compatibility, but a warning will be logged on container startup. Please migrate to `ACME_RENEW_AFTER`.

* `ACME_HTTP_CHALLENGE_LOCATION` - Previously **acme-companion** automatically added the ACME HTTP challenge location to the nginx configuration through files generated in `/etc/nginx/vhost.d`. Recent versions of **nginx-proxy** (>= `1.6`) already include the required location configuration, which remove the need for **acme-companion** to attempt to dynamically add them. If you're running and older version of **nginx-proxy** (or **docker-gen** with an older version of the `nginx.tmpl` file), you can re-enable this behaviour by setting `ACME_HTTP_CHALLENGE_LOCATION` to `true`.

* `ENABLE_IPV6` - Set it to `true` to make the **standalone** ACME HTTP challenge configuration (used for domains not served by **nginx-proxy**, e.g. `ACME_STANDALONE_CERTS`) also listen over IPv6 (`listen [::]:80;`) in addition to IPv4. This matches **nginx-proxy**'s [`ENABLE_IPV6`](https://github.com/nginx-proxy/nginx-proxy#ipv6-support) option, so set the same value on both containers. Leave it unset (or `false`) unless your host and its Docker networking actually support IPv6, otherwise nginx may fail to bind the IPv6 socket. Only the standalone challenge config is affected; challenges served through nginx-proxy already follow nginx-proxy's own IPv6 setting.

* `RELOAD_NGINX_ONLY_ONCE` - The companion reload nginx configuration after every new or renewed certificate. Previously this was done only once per service loop, at the end of the loop (this was causing delayed availability of HTTPS enabled application when multiple new certificates where requested at once, see [issue #1147](https://github.com/nginx-proxy/acme-companion/issues/1147)). You can restore the previous behaviour if needed by setting the environment variable `RELOAD_NGINX_ONLY_ONCE` to `true`.

* `DOCKER_CONTAINER_FILTERS` -  You can filter which containers are considered by acme-companion by using the `DOCKER_CONTAINER_FILTERS` environment variable (by default, acme-companion will consider all running containers). It takes a comma separated list of `key=value` pairs. For example, setting `DOCKER_CONTAINER_FILTERS` environment variable to `network=mynetwork` will cause acme-companion to consider only containers connected to the `mynetwork` network. See the [Docker CLI documentation](https://docs.docker.com/reference/cli/docker/container/ls/#filter) for details on available filters.

* `DOCKER_HOST` - The Docker API endpoint acme-companion talks to. Defaults to `unix:///var/run/docker.sock` (the mounted Docker socket). To connect to a remote or TLS-protected Docker daemon over TCP, set it to `tcp://<host>:<port>` (the conventional Docker TLS port is `2376`).

* `DOCKER_TLS_VERIFY` and `DOCKER_CERT_PATH` - Enable TLS client-certificate authentication when connecting to the Docker daemon over `tcp://`. Set `DOCKER_TLS_VERIFY` to `true` and `DOCKER_CERT_PATH` to the **in-container** path of a directory containing `ca.pem`, `cert.pem` and `key.pem`. These variable names and file names match the [Docker CLI convention](https://docs.docker.com/engine/security/protect-access/) and the ones used by **docker-gen**, so the same certificate directory can be shared across containers.

    > **Important:** `DOCKER_CERT_PATH` is a path **inside the container**. You must mount your certificate directory into the container with a volume, otherwise the files will not be found and the container will exit on startup with an error.

    For example, connecting to a TLS-protected Docker daemon over TCP (note that the Docker socket is **not** mounted in this case):

    ```bash
    $ docker run --detach \
        --name nginx-proxy-acme \
        --volumes-from nginx-proxy \
        --volume certs:/etc/nginx/certs:rw \
        --volume acme:/etc/acme.sh \
        --volume /path/to/docker/certs:/docker-certs:ro \
        --env "DOCKER_HOST=tcp://docker-host.example.com:2376" \
        --env "DOCKER_TLS_VERIFY=true" \
        --env "DOCKER_CERT_PATH=/docker-certs" \
        nginxproxy/acme-companion
    ```