[opensourcedex]

docker-nginx-certbot is a free, open source data security & privacy project written in Shell and released under MIT. It has 1,205 GitHub stars, 195 forks and 8 open issues, and was last pushed 19 hours ago. On this registry it ranks #21 of 22 tracked projects in Data Security & Privacy, with 5 head-to-head comparisons available.

What is docker-nginx-certbot?

docker-nginx-certbot is an MIT-licensed Docker image that bundles Nginx with the certbot ACME client so that websites automatically obtain and renew free Let's Encrypt TLS certificates, and it is aimed at self-hosters and small teams who run their own Nginx servers.

What it is

The project is a Docker image built on top of the official Nginx Docker images, in both Debian and Alpine variants, with the certbot client added so that certificate issuance and renewal happen inside the same container that serves the site. It uses OpenSSL or LibreSSL to automatically create the Diffie-Hellman parameters used during the initial handshake of some ciphers, and it inherits the parent container's /docker-entrypoint.d/ folder so configuration hooks behave as they do in stock Nginx images.

The concrete problem it solves is the manual, error-prone cycle of running certbot, wiring the resulting files into an Nginx configuration, and remembering to renew before expiry. Renewal checks run on an interval controlled by RENEWAL_INTERVAL, which defaults to 8d, so certificates are kept current without operator intervention. The image also replaces the earlier @staticfloat nginx-certbot image: this repository was forked from @henridwyer by @staticfloat and then forked again, and the changes since then are significant enough that it is now an independent repository, with migration instructions documented for users moving off that earlier image.

Key capabilities

  • Requests certificates covering multiple server names in a single run, such as both example.com and www.example.com.
  • Requests wildcard certificates when DNS authentication is configured.
  • Issues both RSA and ECDSA certificates, and can handle both at the same time in a multi-certificate setup.
  • Creates Diffie-Hellman parameters whenever they are defined, with DHPARAM_SIZE defaulting to 2048.
  • Performs a live reload of configurations when the container receives a SIGHUP, with no container restart required.
  • Supports an offline mode against a local certificate authority.
  • Reports a correct exit code when the container is stopped, killed, or fails, and ships Debian and Alpine images built for multiple architectures.

Who uses it and how

  • Self-hosters running Nginx behind NAT who already own a domain pointing at the correct IP address and have ports 80 and 443 forwarded.
  • Operators of dynamic-IP connections who pair the image with a Dynamic DNS provider such as DuckDNS so the certificate requests resolve correctly.
  • Sites needing wildcard coverage, which requires DNS authentication rather than the standard HTTP challenge.
  • Teams that prefer ECDSA by default, using the ELLIPTIC_CURVE setting (default secp256r1) with USE_ECDSA and RSA_KEY_SIZE as the RSA fallback knobs.
  • ARM-based and other multi-architecture hosts, including the armv7 target listed among the project's topics.

Getting started

Pull the published image jonasal/nginx-certbot from Docker Hub using a specific tag rather than :latest, since :latest is not always fully stable, and set the required CERTBOT_EMAIL environment variable along with your Nginx configuration. Set STAGING=1 while testing so requests go to the Let's Encrypt staging servers and you avoid rate limits.

How it compares

No list of commercial or paid products replaced by this project is provided in the facts, and no peer alternative tools are named there either, so it stands alone in this registry among Nginx-and-certbot images. Its only named lineage is the earlier @staticfloat image, from which it has detached as its own repository while retaining the full commit history.

When to use it — and when not to

A self-hoster must operate Docker, own a domain whose ports 80 and 443 are reachable, and accept that the very first container start can take a long time before it responds to requests because the Diffie-Hellman parameters are being generated. It is a poor fit for anyone who cannot control DNS for wildcard certificates or who wants a fully managed certificate service rather than a container to run. The documentation is split across several files, and the README text provided ends mid-section, so prospective users should expect to read docs/good_to_know.md, docs/dockerhub_tags.md, docs/certbot_authenticators.md, and docs/advanced_usage.md before deploying.

project readme (upstream, from github) — read inline

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 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][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

  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][12] as a Dynamic DNS provider, and then either search on how to port forward on your router or maybe find it [here][13].

  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][11] installed for this to function.

Available Environment Variables

Required

  • CERTBOT_EMAIL: Your e-mail address. Used by Let's Encrypt to contact you in case of security issues.

Optional

  • DHPARAM_SIZE: The size of the Diffie-Hellman parameters (default: 2048)
  • ELLIPTIC_CURVE: The size/[curve][15] of the ECDSA keys (default: secp256r1)
  • RENEWAL_INTERVAL: Time interval between certbot's renewal checks (default: 8d)
  • RSA_KEY_SIZE: The size of the RSA encryption keys (default: 2048)
  • STAGING: Set to 1 to use Let's Encrypt's staging servers (default: 0)
  • USE_ECDSA: Set to 0 to have certbot use RSA instead of ECDSA (default: 1)

Advanced

  • CERTBOT_AUTHENTICATOR: The authenticator plugin to use when responding to challenges (default: webroot)
  • CERTBOT_DNS_PROPAGATION_SECONDS: The number of seconds to wait for the DNS challenge to propagate (default: certbot's default)
  • CERTBOT_DNS_CREDENTIALS_DIR: Directory where credentials for DNS authenticators should be located (default: /etc/letsencrypt).
  • DEBUG: Set to 1 to enable debug messages and use the [nginx-debug][10] binary (default: 0)
  • USE_LOCAL_CA: Set to 1 to 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 [email protected] \
           -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][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 ./tests

More Resources

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

  • Good to Know
    • A lot of good to know stuff about this image and the features it provides.
  • Changelog
    • List of all the tagged versions of this repository, as well as bullet points to what has changed between the releases.
  • DockerHub Tags
    • All the tags available from Docker Hub.
  • Advanced Usage
    • Information about the more advanced features this image provides.
  • Certbot Authenticators
    • Information on the different authenticators that are available in this image.
  • Nginx Tips
    • Some interesting tips on how Nginx can be configured.

External Guides

Here is a list of projects that use this image in various

readme truncated — read the full docs on github

Frequently asked questions

Is docker-nginx-certbot free to use?

docker-nginx-certbot is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does docker-nginx-certbot do?

Automatically create and renew website certificates for free using the Let's Encrypt certificate authority.

What is docker-nginx-certbot written in?

docker-nginx-certbot is primarily written in Shell. Its source is publicly available at https://github.com/JonasAlfredsson/docker-nginx-certbot, and it has 1,205 GitHub stars.