Automatically create and renew website certificates for free using the Let's Encrypt certificate authority.
docker-nginx-certbot
Automatically create and renew website SSL certificates using the [Let's Encrypt][1] free certificate authority and its client [certbot][2]. Built on top of the [official Nginx Docker images][9] (both Debian and Alpine), and uses OpenSSL/LibreSSL to automatically create the Diffie-Hellman parameters used during the initial handshake of some ciphers.
:information_source: The very first time this container is started it mighttake a long time before it is ready to respond to requests. Read more about this in the Diffie-Hellman parameters section.
:informationsource: Please use a specific tagwhen doing a Docker pull, since
:latest might not always be 100% stable.
Noteworthy Features
- Handles multiple server names when requesting certificates (i.e. both
example.comandwww.example.com). - Handles wildcard domain request in case you use DNS authentication.
- Can request both RSA and ECDSA certificates (at the same time).
- Will create Diffie-Hellman parameters if they are defined.
- Uses the [parent container][9]'s [
/docker-entrypoint.d/][7] folder. - Will report correct [exit code][6] when stopped/killed/failed.
- You can do a live reload of configs by sending in a
SIGHUPsignal (no container restart needed). - Possibility to use this image offline with the help of a local CA.
- Both Debian and Alpine images built for [multiple architectures][14].
Acknowledgments and Thanks
This container requests SSL certificates from [Let's Encrypt][1], with the help of their [certbot][2] script, which they provide for the absolutely bargain price of free! If you like what they do, please [donate][3].
This repository was originally forked from [@henridwyer][4] by [@staticfloat][5], before it was forked again by me. However, the changes to the code has since become so significant that this has now been detached as its own independent repository (while still retaining all the history). Migration instructions, from @staticfloat's image, can be found here.
Usage
Before You Start
- This guide expects you to already own a domain which points at the correct
80 and 443 correctly forwarded
if you are behind NAT. Otherwise I recommend [DuckDNS][12] as a Dynamic DNS
provider, and then either search on how to port forward on your router or
maybe find it [here][13].
- I suggest you read at least the first two sections in the
- I don't think it is necessary to mention if you managed to find this
Available Environment Variables
Required
CERTBOT_EMAIL: Your e-mail address. Used by Let's Encrypt to contact you in case of security issues.
Optional
DHPARAMSIZE: The size of the Diffie-Hellman parameters (default:2048)ELLIPTIC_CURVE: The size/[curve][15] of the ECDSA keys (default:secp256r1)RENEWALINTERVAL: Time interval between certbot's renewal checks (default:8d)RSAKEYSIZE: The size of the RSA encryption keys (default:2048)STAGING: Set to1to use Let's Encrypt's staging servers (default:0)USEECDSA: Set to0to have certbot use RSA instead of ECDSA (default:1)
Advanced
CERTBOTAUTHENTICATOR: The authenticator plugin to use when responding to challenges (default:webroot)CERTBOTDNSPROPAGATIONSECONDS: The number of seconds to wait for the DNS challenge to propagate (default: certbot's default)CERTBOTDNSCREDENTIALSDIR: Directory where credentials for DNS authenticators should be located (default:/etc/letsencrypt).DEBUG: Set to1to enable debug messages and use the [nginx-debug][10] binary (default:0)USELOCALCA: Set to1to enable the use of a local certificate authority (default:0)
Volumes
/etc/letsencrypt: Stores the obtained certificates and the Diffie-Hellman parameters
Run with docker run
Create your own user_conf.d/
folder and place all of you custom server config files in there. When done you
can just start the container with the following command
(available tags):
docker run -it -p 80:80 -p 443:443 \
--env CERTBOT_EMAIL=your@email.org \
-v $(pwd)/nginx_secrets:/etc/letsencrypt \
-v $(pwd)/userconf.d:/etc/nginx/userconf.d:ro \
--name nginx-certbot jonasal/nginx-certbot:latestYou should be able to detach from the container by holding Ctrl and pressing
p + q after each other.
As was mentioned in the introduction; the very first time this container is started it might take a long time before before it is ready to respond to requests, please be a little bit patient. If you change any of the config files after the container is ready, you can just send in a SIGHUP to tell the scripts and Nginx to reload everything.
docker kill --signal=HUP <container_name>Run with docker-compose
An example of a docker-compose.yaml file can
be found in the examples/ folder. The default parameters that
are found inside the nginx-certbot.env file
will be overwritten by any environment variables you set inside the .yaml
file.
NOTE: You can use bothof them, the only requirement is thatenvironment:andenv_file:together or only one
CERTBOT_EMAIL is defined
somewhere.
Like in the example above, you just need to place your custom server configs inside your user_conf.d/ folder beforehand. Then you start it all with the following command.
docker-compose upBuild It Yourself
This option is for if you make your ownDockerfile. Check out which tags that
are available in this document, or on
[Docker Hub][8], and then choose how specific you want to be.
In this case it is possible to completely skip the user_conf.d/ folder and just write your files directly into Nginx's conf.d/ folder. This way you can replace the files I have built into the image with your own. However, if you do that please take a moment to understand what they do, and what you need to include in order for certbot to continue working.
FROM jonasal/nginx-certbot:latest
COPY conf.d/* /etc/nginx/conf.d/Tests
We make use of [BATS][16] to test parts of this codebase. The easiest way to run all the tests is to execute the following command in the root of this repository:docker run -it --rm -v "$(pwd):/workdir" ffurrer/bats:latest ./testsMore Resources
Here is a collection of links to other resources that provide useful information. - A lot of good to know stuff about this image and the features it provides. - List of all the tagged versions of this repository, as well as bullet points to what has changed between the releases. - All the tags available from Docker Hub. - Information about the more advanced features this image provides. - Information on the different authenticators that are available in this image. - Some interesting tips on how Nginx can be configured.External Guides
Here is a list of projects that use this image in various creative ways. Take a look and see if one of these helps or inspires you to do something similar:[1]: https://letsencrypt.org/ [2]: https://github.com/certbot/certbot [3]: https://letsencrypt.org/donate/ [4]: https://github.com/henridwyer/docker-letsencrypt-cron [5]: https://github.com/staticfloat/docker-nginx-certbot [6]: https://github.com/JonasAlfredsson/docker-nginx-certbot/commit/43dde6ec24f399fe49729b28ba4892665e3d7078 [7]: https://github.com/nginxinc/docker-nginx/tree/master/entrypoint [8]: https://hub.docker.com/r/jonasal/nginx-certbot [9]: https://github.com/nginxinc/docker-nginx [10]: https://github.com/docker-library/docs/tree/master/nginx#running-nginx-in-debug-mode [11]: https://docs.docker.com/engine/install/ [12]: https://www.duckdns.org/ [13]: https://portforward.com/router.htm [14]: https://github.com/JonasAlfredsson/docker-nginx-certbot/issues/28 [15]: https://security.stackexchange.com/a/104991 [16]: https://github.com/bats-core/bats-core
