Automatically create and renew website SSL certificates using the Let's Encrypt free certificate authority and its client certbot. Built on top of the official Nginx Docker images (both Debian and Alpine), and uses OpenSSL/LibreSSL to automatically create the Diffie-Hellman parameters used during the initial handshake of some ciphers.
ℹ️ The very first time this container is started it might take a long time before before it is ready to respond to requests. Read more about this in the Diffie-Hellman parameters section.
This container requests SSL certificates from Let's Encrypt, with the help of their certbot script, which they provide for the absolutely bargain price of free! If you like what they do, please donate.
This repository was originally forked from @henridwyer
by
@staticfloat
, 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.
Some of the more significant additions to this container:
- Handles multiple server names when requesting certificates (i.e. both
example.com
andwww.example.com
). - Can request both RSA and ECDSA keys (at the same time).
- Will create Diffie-Hellman parameters if they are defined.
- Uses the parent container's
/docker-entrypoint.d/
folder. - Will report correct exit code when stopped/killed/failed.
- You can do a live reload of configs by sending in a
SIGHUP
signal (no container restart needed). - Easy to force renewal of certificates if necessary.
- You can tune your own renewal interval.
- Both Debian and Alpine images built for multiple architectures.
-
This guide expects you to already own a domain which points at the correct IP address, and that you have both port
80
and443
correctly forwarded if you are behind NAT. Otherwise I recommend DuckDNS as a Dynamic DNS provider, and then either search on how to port forward on your router or maybe find it here. -
I suggest you read at least the first two sections in the Good to Know documentation, since this will give you some important tips on how to create a basic server config, and how to use the Let's Encrypt staging servers in order to not get rate limited.
-
I don't think it is necessary to mention if you managed to find this repository, but you will need to have Docker installed for this to function.
CERTBOT_EMAIL
: Your e-mail address. Used by Let's Encrypt to contact you in case of security issues.
STAGING
: Set to1
to use Let's Encrypt's staging servers (default:0
)DHPARAM_SIZE
: The size of the Diffie-Hellman parameters (default:2048
)RSA_KEY_SIZE
: The size of the RSA encryption keys (default:2048
)ELLIPTIC_CURVE
: The size/curve of the ECDSA keys (default:secp256r1
)USE_ECDSA
: Set to1
to have certbot use ECDSA keys instead of RSA (default:0
)RENEWAL_INTERVAL
: Time interval between certbot's renewal checks (default:8d
)DEBUG
: Set to1
to enable debug messages and use thenginx-debug
binary (default:0
)
/etc/letsencrypt
: Stores the obtained certificates and the Diffie-Hellman parameters
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)/user_conf.d:/etc/nginx/user_conf.d:ro \
--name nginx-certbot jonasal/nginx-certbot:latest
You should be able to detach from the container by holding
Ctrl
and pressingp
+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 my scripts and
Nginx to reload everything.
docker kill --signal=HUP <container_name>
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.
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 up
This option is for if you make your own Dockerfile
. Check out which tags that
are available in this document, or on Docker Hub, 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/
Here is a collection of links to other resources that provide useful information.
Document with a lot of good to know stuff about this image and the features it provides.
Document with all the tagged versions of this repository, as well as bullet points to what has changed between the releases.