Requests Let's Encrypt certificates using a user-supplied DNS hook
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.
Chris Smith 9149f6bc6a
Update dehydrated and switch to ACMEv2
4 years ago
Dockerfile Update to Dehydrated 0.4.0 6 years ago
LICENCE Update to Dehydrated 0.4.0 6 years ago Add info on accepting terms and conditions. 6 years ago
config Update dehydrated and switch to ACMEv2 4 years ago
dehydrated Update dehydrated and switch to ACMEv2 4 years ago Pass --keep-going to dehydrated. 6 years ago

Let’s Encrypt Generic DNS Service

This container uses dehydrated to automatically obtain SSL certs from Let’s Encrypt.

You need to provide a hook that will perform DNS updates on your domains. If you use a cloud DNS provider, you’re probably better off using letsencrypt-lexicon.

Multiple domains, as well as SANs, are supported. Certificates will be renewed automatically, and obtained automatically as soon as new domains are added.


Accepting Let’s Encrypt’s terms

In order to issue certificates with Let’s Encrypt, you must agree to the Let’s Encrypt terms of service. You can do this by running the command /dehydrated --register --accept-terms from within the container.

For ease of automation, you can define the ACCEPT_CA_TERMS env var (with any non-empty value) to automatically accept the terms. Be warned that doing so will automatically accept any future changes to the terms of service.

Defining domains

The container defines one volume at /letsencrypt, and expects there to be a list of domains in /letsencrypt/domains.txt. Certificates are output to /letsencrypt/certs/{domain}.

domains.txt should contain one line per certificate. If you want alternate names on the cert, these should be listed after the primary domain. e.g.

This will request two certificates: one for with a SAN of, and a separate one for

The container uses inotify to monitor the domains.txt file for changes, so you can update it while the container is running and changes will be automatically applied.


To verify that you own the domain, a TXT record needs to be automatically created for it. For this container, you must provide a hook that can do the update. See the documentation for dehydrated for details on the arguments it takes.

The container expects an executable at /dns/hook, so you’ll need to mount the /dns folder or /dns/hook file when running the container.

Other configuration

For testing purposes, you can set the STAGING environment variable to a non-empty value. This will use the Let’s Encrypt staging server, which has much more relaxed limits.

You should pass in a contact e-mail address by setting the EMAIL env var. This is passed on to Let’s Encrypt, and may be used for important service announcements.

By default this container uses Eliptic Curve keys. You can override this behaviour by setting the ALGORITHM environment variable. Dehydrated supports the following algorithms: rsa, prime256v1 and secp384r1.


Here’s a full worked example:

# The directory we'll use to store the domain list and certificates.
# You could use a docker volume instead.
mkdir /tmp/letsencrypt
echo "" > /tmp/letsencrypt/domains.txt

docker run -d --restart=always \
  -e "" \
  -e "STAGING=true" \
  -v /tmp/letsencrypt:/letsencrypt \
  -v /home/user/my-dns-script:/dns \