Home

Welcome to the letsencrypt-nginx-proxy-companion wiki!

---

letsencrypt-nginx-proxy-companion is a lightweight companion container for nginx-proxy.

It handles the automated creation, renewal and use of Let's Encrypt certificates for proxyed Docker containers.

Features:

• Automated creation/renewal of Let's Encrypt (or other ACME CAs) certificates using simp_le.
• Let's Encrypt / ACME domain validation through http-01 challenge only.
• Automated update and reload of nginx config on certificate creation/renewal.
• Support creation of Multi-Domain (SAN) Certificates.
• Creation of a Strong Diffie-Hellman Group at startup.
• Work with all versions of docker.

Requirements:

• Your host must be publicly reachable on both port 80 and 443.
• Check your firewall rules and do not attempt to block port 80 as that will prevent http-01 challenges from completing.
• The (sub)domains you want to issue certificates for must correctly resolve to the host.
• Your DNS provider must answers correctly to CAA record requests.
• If your (sub)domains have AAAA records set, the host must be publicly reachable over IPv6 on port 80 and 443.

Basic usage with nginx-proxy:

Two writable and a read-only volumes must be declared on the nginx-proxy container so that they can be shared with the letsencrypt-nginx-proxy-companion container:

• /etc/nginx/certs to store certificates, private keys and ACME account keys (readonly for the nginx-proxy container).
• /etc/nginx/vhost.d to change the configuration of vhosts (required so the CA may access http-01 challenge files).
• /usr/share/nginx/html to write http-01 challenge files.

Example of use:

• First start nginx-proxy with the three additional volumes declared:

$ docker run --detach \
    --name nginx-proxy \
    --publish 80:80 \
    --publish 443:443 \
    --volume /etc/nginx/certs:ro \
    --volume /etc/nginx/vhost.d \
    --volume /usr/share/nginx/html \
    --volume /var/run/docker.sock:/tmp/docker.sock:ro \
    jwilder/nginx-proxy

(binding the host /var/run/docker.sock inside the container to /tmp/docker.sock is a requirement of ninx-proxy)

• Second start the letsencrypt-nginx-proxy-companion container, getting the volumes from nginx-proxy with --volumes-from:

$ docker run --detach \
    --volumes-from nginx-proxy \
    --volume /etc/nginx/certs:rw \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro \
    jrcs/letsencrypt-nginx-proxy-companion

Once both container are up and running, start any containers you want proxyed with environment variables VIRTUAL_HOST and LETSENCRYPT_HOST both set to the domain(s) your proxyed container is going to use.

VIRTUAL_HOST control proxying by nginx-proxy and LETSENCRYPT_HOST control certificate creation and SSL enabling by letsencrypt-nginx-proxy-companion. Certificates will only be issued for containers that have both VIRTUAL_HOST and LETSENCRYPT_HOST variables set to domain(s) that correctly resolve to the host, provided the host is reachable.

Albeit optional, it is strongly recommended that you provide a valid email address through the LETSENCRYPT_EMAIL environment variable, so that the Let's Encrypt can warn you about expiring certificates and allow you to recover your account.

$ docker run --detach \
    --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
    --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
    --env "[email protected]" \
    nginx

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. See nginx-proxy docs for more informations.