search

JonasAlfredsson / docker-nginx-certbot

Automatically create and renew website certificates for free using the Let's Encrypt certificate authority.
https://hub.docker.com/r/jonasal/nginx-certbot
MIT License
959 stars 168 forks source link
acme armv7 certbot certificate-authority dhparam dns-01-challange docker ecdsa hacktoberfest https ipv6 letsencrypt live-reload localhost nginx offline-capable ssl ssl-certificates wildcard-certificates

readme

docker-nginx-certbot

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.

:information_source: The very first time this container is started it might take a long time before it is ready to respond to requests. Read more about this in the Diffie-Hellman parameters section.

:information_source: Please use a specific tag when doing a Docker pull, since :latest might not always be 100% stable.

Noteworthy Features

Acknowledgments and Thanks

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.

Usage

Before You Start

  1. This guide expects you to already own a domain which points at the correct IP address, and that you have both port 80 and 443 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.

  2. 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.

  3. 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.

Available Environment Variables

Required

Optional

Advanced

Volumes

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)/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 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 both environment: and env_file: together or only one of them, the only requirement is that 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 up

Build It Yourself

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/

Tests

We make use of BATS 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 ./tests

More Resources

Here is a collection of links to other resources that provide useful information.

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: