You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
ChaosMarc c312c97370 maintainance stop 3 years ago
app Use multiple methods to obtain self cid (#499) 3 years ago
docs [skip ci] Update test certificate doc (#497) 3 years ago
test Added test unit for LETSENCRYPT_MIN_VALIDITY environment variable 3 years ago
.dockerignore [skip ci] Documentation rework (#493) 3 years ago
.gitignore * Added new test unit to test LETSENCRYPT_RESTART_CONTAINER variable functionality 3 years ago
.travis.yml Update docker-compose in test suite (#486) 3 years ago
Dockerfile Update build stage to golang 1.11 (#487) 3 years ago
LICENSE Add LICENSE file 6 years ago maintainance stop 3 years ago Update simp_le to 0.13.0 (#515) 3 years ago
schema.png add schema 4 years ago Update 3 years ago

THIS IMAGE IS NO LONGER MAINTAINED. PLEASE USE THE IMAGE at alexanderkrause/rpi-letsencrypt-nginx-proxy-companion

armhf port of jrcs/letsencrypt-nginx-proxy-companion: keksnase/letsencrypt-nginx-proxy-companion-armhf

Build Status GitHub release Image info Docker stars Docker pulls

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.

Please note that letsencrypt-nginx-proxy-companion does not work with ACME v2 endpoints yet.


  • 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.


  • 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.
  • For the same reason, you can't use nginx-proxy's HTTPS_METHOD=nohttp.
  • 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 the nginx-proxy container)

Three writable 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:

Step 1 - nginx-proxy

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 \
    --volume /etc/nginx/vhost.d \
    --volume /usr/share/nginx/html \
    --volume /var/run/docker.sock:/tmp/docker.sock:ro \

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

Step 2 - letsencrypt-nginx-proxy-companion

Start the letsencrypt-nginx-proxy-companion container, getting the volumes from nginx-proxy with --volumes-from:

$ docker run --detach \
    --name nginx-proxy-letsencrypt \
    --volumes-from nginx-proxy \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro \

The host docker socket has to be bound inside this container too, this time to /var/run/docker.sock.

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.

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 publicly reachable.

$ docker run --detach \
    --name your-proxyed-app \
    --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
    --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
    --env "LETSENCRYPT_EMAIL=mail@yourdomain.tld" \

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 environment variable.

Example using Grafana (expose and listen on port 3000):

$ docker run --detach \
    --name grafana \
    --env "VIRTUAL_HOST=othersubdomain.yourdomain.tld" \
    --env "VIRTUAL_PORT=3000" \
    --env "LETSENCRYPT_HOST=othersubdomain.yourdomain.tld" \
    --env "LETSENCRYPT_EMAIL=mail@yourdomain.tld" \

Repeat Step 3 for any other container you want to proxy.

Additional documentation

Please check the docs section or the project's wiki.