Open Source and free to use certbot for Docker environments to automate the Let's Encrypt's certificate issuing and renewal. The Docker image is based on Alpine Linux and uses certbot under the hood.
- Obtain certificates from Let's Encrypt
- Renew obtained certificates with configurable cronjobs
- Renewal hooks (pre, post and deploy hooks are supported out-of-the-box)
- Install certbot's DNS plugins with pip when starting the Docker container
- Efficient signal handling with Tini
- Highly configurable with environment variables
- Capable to obtain and automatically renew multiple certificates (since version 1.1.0)
- Getting Started
- Multiple Certificates
- Environment Variables
- Volumes
- Exposed Ports
- Building from Source
- Reporting Issues
- License
Ensure that your domain points to an valid IP address before you start.
Run certbot once:
docker run -it -p 80:80 -v $(pwd)/data/certbot:/etc/letsencrypt \
-e EMAIL=your@email.com \
-e DOMAINS=example.com,www.example.com \
-e RUN_ONCE=1 \
--name certbot nbraun1/certbotRun certbot with cronjobs:
docker run -it -p 80:80 -v $(pwd)/data/certbot:/etc/letsencrypt \
-e EMAIL=your@email.com \
-e DOMAINS=example.com,www.example.com \
-e CRON="0 0,12 * * *" \
--name certbot nbraun1/certbotRun certbot listens to another port for http-01 challenge:
docker run -it -p 80:81 -v $(pwd)/data/certbot:/etc/letsencrypt \
-e EMAIL=your@email.com \
-e DOMAINS=example.com,www.example.com \
-e RUN_ONCE=1 \
-e HTTP01_PORT=81 \
--name certbot nbraun1/certbotCertbot listens to port 81 in the Docker container but is mapped as port 80 to the host in order to be reachable for a ACME server.
Run certbot for multiple certificates:
docker run -it -p 80:80 \
-v $(pwd)/data/certbot:/etc/letsencrypt \
-v $(pwd)/example.ini:/etc/certbot/multi-certificates.ini \
-e ENABLE_MULTI_CERTIFICATES=1 \
--name certbot nbraun1/certbotFor detailed information how the multi-certificates feature works, read the multiple certificates section.
For an example to run certbot in Docker Compose consult our docker-compose.yml. In order to start the certbot run docker compose up in your command line. More examples can be found in the examples directory.
Note that we use Docker Compose V2 for this example.
Are you tired of running multiple docker run commands for the same certbot Docker image to obtain or renew multiple certificates? Or repeat your certbot service in your docker-compose.yml where each of them manage a separate domain? Or write the ugly configuration for one certbot service to force a semi multi-certificates feature? Our Docker image provides a much simpler and more pleasant way!
Our multi-certificates feature is based on an INI file which is written by you. For an simple example have a look at our pre-defined example.ini file. This whole feature is optional, means that you can decide with the ENABLE_MULTI_CERTIFICATES environment variable if you enable or disable it. In the run with docker run section you safely noticed that an additional volume is used when running with an defined ENABLE_MULTI_CERTIFICATES environment variable. This volume only contains the INI file and is located at /etc/certbot/multi-certificates.ini in the Docker container by default. That location can be changed with the MULTI_CERTIFICATES_INI_FILE environment variable.
The INI file contains one optional DEFAULT section and one or more domain specific sections. Each option defined in the DEFAULT section is applied to the domain specific section options. If a DEFAULT option is the same as the domain specific one, the domain specific one overrides the DEFAULT one and is used. Possible options and its values are the environment variables defined in the corresponding section.
Reading this section is not mandatory to understand the multi-certificates feature but might be helpfully if you are interested in general technical background knowledge.
To parse the INI file we use Python and not Bash! You might be wondering: "Why using Python to parse a file in a Docker container which uses Bash by default?!". The answer is really simple. There are a handful existing INI file parsers available in GitHub but most of these are either a (dirty) hack, incomplete, do not work or do not meet our requirements. The alternatives are e.g awk or sed scripts but we think this kind of solution is not maintainable, not really smart and above all error prone. So we decided to use Python and its config parser module to parse the INI file.
This section is partially based on the official certbot command line options documentation. Most of the environment variables defaults to an empty string which is in most cases equivalent to a boolean false. If you wish to set this environment variable to a boolean true, leave its value to 1 or any other non-empty string. There are also some environment variables wish require a string or number but each of them have a well documentation to describe its expectation.
EMAIL
One or more email addresses separated by commas used for account registration and important notifications.
DOMAINS
Comma separated list of domains which should be protected by the obtained certificate. The first domain in this list will be always the subject CN (Common Name) and all domains will be the SANs (Subject Alternative Names) in this certificate. In addition to that the first domain is used for the file name of the obtained certificate. In the case of a name collision it will append a number like 0001 to the file name. If you want to use another value for the file name use the
CERT_NAMEenvironment variable.
CERT_NAME
The name of the obtained certificate used for its file name. This value does not effect the certificate's content itself.
PREFERRED_CHALLENGES
Sorted, comma separated list of preferred challenges used for authorization. Each challenge has a version but if you set e.g "http" as
PREFERRED_CHALLENGES, certbot will select the latest version automatically. If no value is set for this environment variable, we try to auto-detect this value based on the configuredAUTHENTICATORenvironment variable. The table below shows eachPREFERRED_CHALLENGESwhich is used by anAUTHENTICATORby default:
| AUTHENTICATOR | PREFERRED_CHALLENGES |
|---|---|
| webroot | http-01 |
| standalone | http-01 |
| dns | dns-01 |
ISSUANCE_TIMEOUT
The duration in seconds how long certbot will wait for the ACME server to issue a certificate. Default is 90 seconds.
MAX_LOG_BACKUPS
The maximum number of backup logs which should be kept by certbot's built-in log rotation. If set this value to 0, log rotation is disabled and certbot will always write to the same log file. It might be useful to set this value to 0 if you want to use external log rotation software like logrotate.
FORCE_RENEWAL
Force certbot to renew a certificate if exists and regardless of whether it is near expiry.
QUIET
Silence all output except errors.
AUTHENTICATOR
Name of the authenticator plugin. Default is standalone.
HTTP01_ADDRESS
The address the server listens to during http-01 challenge. Applied if
AUTHENTICATORis standalone.
HTTP01_PORT
Port used in the http-01 challenge. Applied if
AUTHENTICATORis standalone.
WEBROOT_PATH
Path to the top-level directory containing the files served by your webserver. Applied if
AUTHENTICATORis webroot andWEBROOT_PATHis required in this case.
DNS_AUTHENTICATOR_CREDENTIALS
DNS provider credentials INI file. Applied if
AUTHENTICATORis from type dns.
DNS_PROPAGATION_SECONDS
The number of seconds to wait for DNS to propagate before asking the ACME server to verify the DNS record. Applied if
AUTHENTICATORis from type dns.
DNS_PLUGIN_FLAGS
Additional command line options for the DNS plugin.
STAGING
Use the staging server to obtain or revoke test (invalid) certificates; equivalent to set the environment variable
SERVERtohttps://acme-staging-v02.api.letsencrypt.org/directory.
VERBOSE
Make certbot's output verbose.
DEBUG
Show tracebacks in case of errors.
RSA_KEY_SIZE
Size of the RSA key. Default is 2048.
KEY_TYPE
Type of generated private key. Can be either
rsaorecdsa.
ELLIPTIC_CURVE
The SECG elliptic curve name to use. Default is secp256r1.
SERVER
ACME Directory Resource URI. Default is
https://acme-v02.api.letsencrypt.org/directory.
PRE_HOOK_CMD
Command to be run in a shell before obtaining any certificates. Can be used for renewal to temporarily shutdown your webserver that might conflict with the standalone plugin. This will only be called if a certificate is actually to be obtained/renewed. When renewing several certificates that have identical pre-hooks, only the first will be executed.
POST_HOOK_CMD
Command to be run in a shell after attempting to obtain/renew certificates. Can be used to deploy renewed certificates or to restart any servers that were stopped by
PRE_HOOK_CMD. This is only run if an attempt was made to obtain/renew a certificate. If multiple renewed certificates have identical post-hooks, only one will be run.
DEPLOY_HOOK_CMD
Command to be run in a shell once for each successfully issued certificate. For this command, the shell variable $RENEWED_LINEAGE will point to the
/etc/letsencryptlive subdirectory (for example, "/etc/letsencrypt/live/example.com") containing the new certificates and keys; the shell variable $RENEWED_DOMAINS will contain a space separated list of renewed certificate domains (for example, "example.com www.example.com").
CERTBOT_CERTONLY_FLAGS
Additional command line options for certbot's certonly command.
CERTBOT_RENEW_FLAGS
Additional command line options for certbot's renew command.
DNS_PLUGINS
Comma separated list of DNS plugin names which will be installed with pip.
RUN_ONCE
If defined, the
CRONenvironment variable is ignored and certbot runs only once.
CRON
Cron expression for certbot's automatically renewal. If you have no idea of how to write such an cron expression, use crontab guru to generate one.
ENABLE_MULTI_CERTIFICATES
If defined, the multi-certificates feature is enabled. Disabled by default.
MULTI_CERTIFICATES_INI_FILE
Change the default INI file location from
/etc/certbot/multi-certificates.inito another one. Ignored ifENABLE_MULTI_CERTIFICATESis undefined.
/etc/letsencrypt- stores the obtained certificates./etc/certbot/multi-certificates.ini- the INI file for the multi-certificates feature. Must be mounted manually and is optional, i.e is not exposed by the Dockerfile.
- 80
Checkout this repository and run docker build -t nbraun1/certbot . in the project's root directory. You can use any arbitrary Docker tag. Use the built tag in your docker run command or in your docker-compose.yml to apply your modifications.
If you found a bug or miss a feature, feel free to create an issue in GitHub's integrated issue tracker. But before doing so, please check if there is already an issue which describes your bug or feature in a similar fashion.
This certbot is Open Source software released under the Apache 2.0 license.