Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/joseluisq/docker-lets-encrypt
A multi-arch Let's Encrypt Docker image using Lego CLI client with convenient environment variables and auto-renewal support.
https://github.com/joseluisq/docker-lets-encrypt
acme acme-client auto-renewal certificate crontab debian-linux dns docker-image lego lets-encrypt security tls-certificate
Last synced: 26 days ago
JSON representation
A multi-arch Let's Encrypt Docker image using Lego CLI client with convenient environment variables and auto-renewal support.
- Host: GitHub
- URL: https://github.com/joseluisq/docker-lets-encrypt
- Owner: joseluisq
- License: apache-2.0
- Created: 2024-03-21T23:36:03.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2024-04-07T14:26:47.000Z (7 months ago)
- Last Synced: 2024-05-23T09:20:57.889Z (6 months ago)
- Topics: acme, acme-client, auto-renewal, certificate, crontab, debian-linux, dns, docker-image, lego, lets-encrypt, security, tls-certificate
- Language: Shell
- Homepage: https://hub.docker.com/r/joseluisq/docker-lets-encrypt
- Size: 26.4 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# Docker Let's Encrypt
> A multi-arch [Let's Encrypt](https://letsencrypt.org/) Docker image using [Lego CLI](https://go-acme.github.io/lego/) client with convenient environment variables and auto-renewal support on top of the latest __Debian [12-slim](https://hub.docker.com/_/debian/tags?page=1&name=12-slim)__ ([Bookworm](https://www.debian.org/News/2023/20230610)).
## Usage
Run the Docker image
```sh
# Run Lego CI directly with a particular argument
docker run --rm joseluisq/docker-lets-encrypt -v
# Or run the Docker image in interactive mode
docker run -it --rm joseluisq/docker-lets-encrypt bash
```
Or extend it
```Dockerfile
FROM joseluisq/docker-lets-encrypt
# your stuff...
```
## Examples
Below is an example of obtaining a **wildcard certificate** using the **Cloudflare** provider.
In this case, make sure to create first a [Cloudflare API User Token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) for your specific domain with the `DNS:Edit` permission.
### Using Docker run
```sh
docker run -it --rm \
# Lego CLI options
-e ENV_LEGO_ENABLE=true \
-e ENV_LEGO_ACCEPT_TOS=true \
-e [email protected] \
-e ENV_LEGO_DOMAINS="*.domain.com" \
# Lego CLI DNS provider
-e ENV_LEGO_DNS=cloudflare \
-e [email protected] \
-e CLOUDFLARE_DNS_API_TOKEN= \
# TLS auto-renewal feature (optional)
-e ENV_CERT_AUTO_RENEW=true \
-e ENV_CERT_AUTO_RENEW_CRON_INTERVAL="0 0 * * *" \
# Directory mapping (bind mount) for certificate/key files
-v /etc/ssl/certs/domain.com:/etc/ssl/.lego \
joseluisq/docker-lets-encrypt
# 2024/01/01 00:00:30 [INFO] [*.domain.com] acme: Obtaining bundled SAN certificate
# 2024/01/01 00:00:31 [INFO] [*.domain.com] AuthURL: https://acme-v02.api.letsencrypt.org/acme/authz-v3/000000000000
# 2024/01/01 00:00:31 [INFO] [*.domain.com] acme: use dns-01 solver
# 2024/01/01 00:00:31 [INFO] [*.domain.com] acme: Preparing to solve DNS-01
# 2024/01/01 00:00:31 [INFO] Found CNAME entry for "_acme-challenge.domain.com.": "dns.domain.com."
# 2024/01/01 00:00:32 [INFO] cloudflare: new record for domain.com, ID 1234567a8e000d0ab0ced00fgjk123e
# 2024/01/01 00:00:32 [INFO] [*.domain.com] acme: Trying to solve DNS-01
# 2024/01/01 00:00:32 [INFO] Found CNAME entry for "_acme-challenge.domain.com.": "dns.domain.com."
# 2024/01/01 00:00:32 [INFO] [*.domain.com] acme: Checking DNS record propagation. [nameservers=127.0.0.2:00]
# 2024/01/01 00:00:34 [INFO] Wait for propagation [timeout: 2m0s, interval: 2s]
# 2024/01/01 00:00:40 [INFO] [*.domain.com] The server validated our request
# 2024/01/01 00:00:40 [INFO] [*.domain.com] acme: Cleaning DNS-01 challenge
# 2024/01/01 00:00:40 [INFO] Found CNAME entry for "_acme-challenge.domain.com.": "dns.domain.com."
# 2024/01/01 00:00:41 [INFO] [*.domain.com] acme: Validations succeeded; requesting certificates
# 2024/01/01 00:00:42 [INFO] [*.domain.com] Server responded with a certificate.
```
**Notes:**
- `ENV_LEGO_ACCEPT_TOS=true` is used to accept the [Let's Encrypt terms of service](https://community.letsencrypt.org/tos).
- The container `.lego` directory will contain the certificates and keys, make sure to bind it to a specific host directory. See https://go-acme.github.io/lego/usage/cli/general-instructions/
- See the **Cloudflare** provider options for more details https://go-acme.github.io/lego/dns/cloudflare/
### Using Docker Compose
Below is an equivalent example like above but using [Docker Compose](https://docs.docker.com/compose/intro/features-uses/).
```yaml
version: "3.3"
services:
joseluisq-net:
image: joseluisq/docker-lets-encrypt:0.0.3
environment:
# Lego CLI options
- "ENV_LEGO_ENABLE=true"
- "ENV_LEGO_ACCEPT_TOS=true"
- "ENV_LEGO_EMAIL=${ENV_LEGO_EMAIL}"
- "ENV_LEGO_DOMAINS=*.domain.com"
# Lego CLI DNS provider
- "ENV_LEGO_DNS=cloudflare"
- "CLOUDFLARE_EMAIL=${CLOUDFLARE_EMAIL}"
- "CLOUDFLARE_DNS_API_TOKEN=${CLOUDFLARE_DNS_API_TOKEN}"
# TLS auto-renewal feature (optional)
- "ENV_CERT_AUTO_RENEW=true"
- "ENV_CERT_AUTO_RENEW_CRON_INTERVAL=0 0 * * *"
volumes:
# Directory mapping (bind mount) for certificate/key files
- /etc/ssl/certs/domain.com:/etc/ssl/.lego
deploy:
replicas: 1
update_config:
parallelism: 1
restart_policy:
condition: on-failure
```
## Environment variables
The image provides environment variables support for several [Lego CLI](https://go-acme.github.io/lego/usage/cli/) arguments.
Below are the environment variables supported and their default values.
### Activation
To activate the environment variables support, set `ENV_LEGO_ENABLE=true`.
- `ENV_LEGO_ENABLE=false`
### General options
- `ENV_LEGO_EMAIL`
- `ENV_LEGO_DOMAINS`
- `ENV_LEGO_SERVER`
- `ENV_LEGO_CSR`
- `ENV_LEGO_ACCEPT_TOS=false`
- `ENV_LEGO_PATH=/etc/ssl/.lego` Directory to use for storing the data.
### Challenge types
- `ENV_LEGO_HTTP=false`
- `ENV_LEGO_DNS` See Lego DNS providers supported https://go-acme.github.io/lego/dns/#dns-providers
### Obtain a new certificate
- `ENV_LEGO_RUN_HOOK`
By default, the **Lego CLI** `run` subcommand will be executed, which will [obtain a new certificate](https://go-acme.github.io/lego/usage/cli/obtain-a-certificate/).
### Renew existing certificate
To [renew a certificate](https://go-acme.github.io/lego/usage/cli/renew-a-certificate/), use the following environment variables instead.
- `ENV_LEGO_RENEW=false` It tells Lego CLI to perform a `renewal` operation on demand.
- `ENV_LEGO_RENEW_DAYS`
- `ENV_LEGO_RENEW_HOOK`
#### Certificate auto-renew
**NOTE:** the auto-renew feature is limited to one domain for now.
- `ENV_CERT_AUTO_RENEW=false` Enable the auto-renew feature
- `ENV_CERT_AUTO_RENEW_DAYS_BEFORE_EXPIRE=3` The days before the certificate expiration to perform a renewal try.
- `ENV_CERT_AUTO_RENEW_CRON_INTERVAL=0 0 * * *` The Crontab interval for the auto-renew checker (default, once a day)
When the option is `ENV_CERT_AUTO_RENEW=true` then a script will programmatically check the certificate days before the expiration (`ENV_CERT_AUTO_RENEW_DAYS_BEFORE_EXPIRE`) and will perform a renewal try.
Keep in mind that `ENV_LEGO_RENEW` should be disabled (`false`) when using this feature because it refers to the Lego CLI `renew` operation (subcommand).
### Additional arguments
- `ENV_LEGO_ARGS`
Print all available Lego CLI options.
```sh
# global options
docker run --rm joseluisq/docker-lets-encrypt -h
# or specific subcommand options
docker run --rm joseluisq/docker-lets-encrypt lego run -h
```
For more details check out the [Lego CLI](https://go-acme.github.io/lego/usage/cli/) available options.
## Contributions
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in current work by you, as defined in the Apache-2.0 license, shall be dual licensed as described below, without any additional terms or conditions.
Feel free to send some [Pull request](https://github.com/joseluisq/docker-lets-encrypt/pulls) or file an [issue](https://github.com/joseluisq/docker-lets-encrypt/issues).
## License
This work is primarily distributed under the terms of both the [MIT license](LICENSE-MIT) and the [Apache License (Version 2.0)](LICENSE-APACHE).
© 2024-present [Jose Quintana](https://joseluisq.net)