Public | Automated Build

Last pushed: 7 days ago
Short Description
Let’s Encrypt (webroot) in a Docker.
Full Description

Let’s Encrypt (webroot) in a Docker

Letsencrypt cert auto getting and renewal script based on letsencrypt base image.


This project is effectively unmaintained. I will do my best to shepherd pull requests, but cannot guarantee a prompt response and do not have bandwidth to address issues or add new features. Please let me know via an issue if you'd be interested in taking ownership of docker-letsencrypt-webroot.


  • First, you need to set up your web server so that it gave the contents of the /.well-known/acme-challenge directory properly.
    Example, for nginx add location for your server:
      location '/.well-known/acme-challenge' {
          default_type "text/plain";
          root        /tmp/letsencrypt;
  • Then run your web server image with letsencrypt-webroot connected volumes:
     -v /data/letsencrypt:/etc/letsencrypt
     -v /data/letsencrypt-www:/tmp/letsencrypt
  • Run letsencrypt-webroot image:

     docker run \
       --name some-letsencrypt \
       -v /data/letsencrypt:/etc/letsencrypt \
       -v /data/letsencrypt-www:/tmp/letsencrypt \
       -e '' \
       -e 'EMAIL=your@email.tld' \
       -e 'WEBROOT_PATH=/tmp/letsencrypt' \
  • Configure your app to use certificates in the following path:

    • Private key: /etc/letsencrypt/live/
    • Certificate: /etc/letsencrypt/live/
    • Intermediates: /etc/letsencrypt/live/
    • Certificate + intermediates: /etc/letsencrypt/live/

NOTE: You should connect /etc/letsencrypt directory fully, because if you connect just /etc/letsencrypt/live, then symlinks to your certificates inside it will not work!

Renew hook

You can also assign hook for your container, it will be launched after letsencrypt receive a new certificate.

  • This feature requires a passthrough docker.sock into letsencrypt container: -v /var/run/docker.sock:/var/run/docker.sock
  • Also add --link to your container. Example: --link some-nginx
  • Then add LE_RENEW_HOOK environment variable to your container:

Example hooks:

  • nginx reload: -e 'LE_RENEW_HOOK=docker kill -s HUP @CONTAINER_NAME@'
  • container restart: -e 'LE_RENEW_HOOK=docker restart @CONTAINER_NAME@'

For more detailed example, see the docker-compose configuration


This is example of letsencrypt-webroot with nginx configuration:


  restart: always
  image: nginx
    - /etc/localtime:/etc/localtime:ro
    - ./nginx:/etc/nginx:ro
    - ./letsencrypt/conf:/etc/letsencrypt
    - ./letsencrypt/html:/tmp/letsencrypt
    - 80:80
    - 443:443
    - LE_RENEW_HOOK=docker kill -s HUP @CONTAINER_NAME@

  restart: always
  image: kvaps/letsencrypt-webroot
    - /etc/localtime:/etc/localtime:ro
    - /var/run/docker.sock:/var/run/docker.sock
    - ./letsencrypt/conf:/etc/letsencrypt
    - ./letsencrypt/html:/tmp/letsencrypt
    - nginx
    - EMAIL=your@email.tld
    - WEBROOT_PATH=/tmp/letsencrypt
    - EXP_LIMIT=30
    - CHECK_FREQ=30
    - STAGING=

Once run

You also can run it with once mode, just add once in your docker command.
With this option a container will exited right after certificates update.

Environment variables

  • DOMAINS: Domains for your certificate. Example to
  • EMAIL: Email for urgent notices and lost key recovery. Example to `your@email.tld`.
  • WEBROOT_PATH Path to the letsencrypt directory in the web server for checks. Example to /tmp/letsencrypt.
  • CHOWN Owner for certs. Defaults to root:root.
  • CHMOD Permissions for certs. Defaults to 644.
  • EXP_LIMIT The number of days before expiration of the certificate before request another one. Defaults to 30.
  • CHECK_FREQ: The number of days how often to perform checks. Defaults to 30.
  • CHICKENEGG: Set this to 1 to generate a self signed certificate before attempting to start the process with no previous certificate. Some http servers (nginx) might not start up without a certificate file present.
  • STAGING: Set this to 1 to use the staging environment of letsencrypt to prevent rate limiting while working on your setup.
Docker Pull Command