Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nginx-le/nginx-le

Nginx with automatic let's encrypt (docker image)
https://github.com/nginx-le/nginx-le

automation docker letsencrypt nginx proxy ssl-certificates

Last synced: about 1 month ago
JSON representation

Nginx with automatic let's encrypt (docker image)

Host: GitHub
URL: https://github.com/nginx-le/nginx-le
Owner: nginx-le
License: apache-2.0
Created: 2016-07-07T06:37:29.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2024-09-07T17:53:33.000Z (4 months ago)
Last Synced: 2024-09-07T19:05:46.763Z (4 months ago)
Topics: automation, docker, letsencrypt, nginx, proxy, ssl-certificates
Language: Shell
Homepage:
Size: 88.9 KB
Stars: 636
Watchers: 19
Forks: 118
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

# NGINX-LE - Nginx web and proxy with automatic let's encrypt [![Docker Automated build](https://img.shields.io/docker/automated/jrottenberg/ffmpeg.svg)](https://hub.docker.com/r/umputun/nginx-le/)

Simple nginx image (alpine based) with integrated [Let's Encrypt](https://letsencrypt.org) support.

## How to use

- get [docker-compose.yml](https://github.com/umputun/nginx-le/blob/master/docker-compose.yml) and change things:
- set timezone to your local, for example `TZ=UTC`. For more timezone values check `/usr/share/zoneinfo` directory
- set `LETSENCRYPT=true` if you want an automatic certificate install and renewal
- `LE_EMAIL` should be your email and `LE_FQDN` for domain
- for multiple FQDNs you can pass comma-separated list, like `LE_FQDN=aaa.example.com,bbb.example.com`
- alternatively set `LETSENCRYPT` to `false` and pass your own cert in `SSL_CERT`, key in `SSL_KEY` and `SSL_CHAIN_CERT`
- `LE_ADDITIONAL_OPTIONS` can be set to anything you want to append to certbot, for example `LE_ADDITIONAL_OPTIONS=--preferred-chain "ISRG Root X1" --debug`.
- use provided `etc/service-example.conf` to make your own `etc/service.conf`. Keep ssl directives as is:
```nginx
ssl_certificate SSL_CERT;
ssl_certificate_key SSL_KEY;
ssl_trusted_certificate SSL_CHAIN_CERT;
```
- make sure `volumes` in docker-compose.yml changed to your service config
- you can map multiple custom config files to in compose using `service*.conf` filename pattern,
see `service2.conf` in [docker-compose.yml](https://github.com/nginx-le/nginx-le/blob/master/docker-compose.yml)
file for reference

Alternatively, mount directory with `*.conf` files into `/etc/nginx/conf.d-le` directory inside
the container to have them all copied at once.
- `stream*.conf` files are picked up into `/etc/nginx/stream.d/` directory and included into `stream`
section of the Nginx configuration, see `stream2.conf` in `docker-compose.yml` file for reference.

Alternatively, mount directory with `*.conf` files into `/etc/nginx/conf.d-le` directory inside
the container to have them all copied at once.
- pull image - `docker-compose pull`
- if you don't want a pre-built image, make you own. `docker-compose build` will do it
- start it `docker-compose up`

### Configuration files variables replacement

On start of the container all following text matches in custom configuration files you mounted will be replaced,
variable with dollar sign (`$`, like `$LE_FQDN`) will be taken from environment, please see next table for their list.

| Matching pattern | Value | nginx usage | Description |
| ---------------- | ----- | ----------- | ----------- |
| SSL_CERT | `/etc/nginx/ssl/$SSL_CERT` | `ssl_certificate` | Public SSL certificate, sent to client |
| SSL_KEY | `/etc/nginx/ssl/$SSL_KEY` | `ssl_certificate_key` | SSL private key, not sent to client |
| SSL_CHAIN_CERT | `/etc/nginx/ssl/$SSL_CHAIN_CERT` | `ssl_trusted_certificate` | Trusted SSL certificates, not sent to client |
| LE_FQDN | `$LE_FQDN` | `server_name` | List of domains, useful for configuration with single `server` block |

### Environment variables list

| Variable | Default value | Description |
| -------- | ------------- | ----------- |
| SSL_CERT | `le-key.pem` | certbot `privkey.pem` new filename |
| SSL_KEY | `le-crt.pem` | certbot `fullchain.pem` new filename |
| SSL_CHAIN_CERT | `le-chain-crt.pem` | certbot `chain.pem` new filename |
| LETSENCRYPT | `false` | Enables Let's Encrypt certificate retrieval and renewal |
| LE_FQDN | | comma-separated list of domains for Let's Encrypt certificate, required if `LETSENCRYPT` is `true` |
| LE_EMAIL | | comma-separated list of emails for Let's Encrypt certificate, required if `LETSENCRYPT` is `true` |
| LE_ADDITIONAL_OPTIONS | | Additional options to be appended to certbot command |
| TZ | | Timezone, if set will be written to container's `/etc/timezone` |

### `envsubst` templates

If you need to use any other environment variables you could mount your configuration as `/etc/nginx/templates/yourservice.conf.template` and `envsubsts` would be executed on that file. More info could be found [here](https://github.com/docker-library/docs/tree/master/nginx#using-environment-variables-in-nginx-configuration-new-in-119)

## Some implementation details

**Important:** provided [nginx.conf](https://github.com/umputun/nginx-le/blob/master/conf/nginx.conf) handles
http->https redirect automatically, no need to add it into your custom `service.conf`. In case if you need a custom server on
http (:80) port, make sure you [handle](https://github.com/umputun/nginx-le/blob/master/conf/nginx.conf#L62) `/.well-known/`
path needed with `root` set for LE challenge: `location /.well-known/ {root /usr/share/nginx/html;}`

- image uses alpine's `certbot` package.
- `script/entrypoint.sh` requests LE certificate and will refresh every 10 days in case if certificate is close to expiration (30day)
- `script/le.sh` gets SSL
- nginx-le on [docker-hub](https://hub.docker.com/r/umputun/nginx-le/)
- **A+** overall rating on [ssllabs](https://www.ssllabs.com/ssltest/index.html)

![ssllabs](https://github.com/umputun/nginx-le/blob/master/rating.png)

## Alternatives

- [Reproxy](https://reproxy.io) simple edge HTTP(s) server / reverse proxy supporting various providers.
- [Træfik](https://traefik.io) HTTP reverse proxy and load balancer. Supports Let's Encrypt directly.
- [Caddy](https://caddyserver.com) supports Let's Encrypt directly.
- [leproxy](https://github.com/artyom/leproxy) small and nice (stand alone) https reverse proxy with automatic Letsencrypt
- [bunch of others](https://github.com/search?utf8=✓&q=nginx+lets+encrypt)

## Examples

- [Reverse proxy](https://github.com/umputun/nginx-le/tree/master/example/webrtc) for WebRTC solutions,
where you need multiple ports on one domain to reach different services behind your `nginx-le` container.

## Manual certificate renewal (`*.example.com`, DNS challenge)

wildcard certificate renewal

In your `docker-compose.yml` disable automatic Let's Encrypt certificate creation/renewal.
```yaml
environment:
- LETSENCRYPT=true
```

```shell
# after starting nginx-le connect to it
docker exec -it nginx sh

# change `*.example.com` to your domain name
certbot certonly \
--manual \
--manual-public-ip-logging-ok \
--preferred-challenges=dns \
--email "${LE_EMAIL}" \
--agree-tos \
-d "*.example.com"

# it will ask you to create/update TXT DNS record
# depending on your DNS provider it can take some time
# you can check if DNS is already updated using dig utility
dig txt _acme-challenge.example.com

# copy certificates for nginx-le to use them
cp -fv /etc/letsencrypt/live/example.com/privkey.pem /etc/nginx/ssl/le-key.pem
cp -fv /etc/letsencrypt/live/example.com/fullchain.pem /etc/nginx/ssl/le-crt.pem
cp -fv /etc/letsencrypt/live/example.com/chain.pem /etc/nginx/ssl/le-chain-crt.pem

# use the same procedure for renewal
```