megavolts/lego_cli repository overview

⁠Let's Encrypt GO CLI docker

⁠Usage

Run the Docker image

# Run Lego CI directly with a particular argument
docker run --rm megavolts/lego_cli -v

# Or run the Docker image in interactive mode
docker run -it --rm megavolts/lego_cli /bin/sh

⁠Examples

Below is an example of obtaining a wildcard certificate using the Porkbun provider using the DNS challenge.

In this case, make sure to create first a Porkbun API Token⁠ for your account, and enable API token for the domain.

⁠Using Docker run

docker run -it --rm \
    # Lego CLI options
    -e LEGO_ENABLE=true \
    -e LEGO_ACCEPT_TOS=true \
    -e LEGO_EMAIL=${LEGO_EMAIL} \
    -e LEGO_DOMAINS=domain.tld,subdomain.domain.tld \
    # Lego CLI DNS provider for porkbun
    -e LEGO_DNS=porkbun \
    -e PORKBUN_API_KEY=${PORKBUN_API_KEY} \
    -e PORKBUN_SECRET_API_KEY=${PORKBUN_SECRET_API_KEY} \
    # Autorenewal option
    -e AUTORENEW=true \
    # Directory mapping (bind mount) for certificate/key files
    -v ./ssl:/opt/lego/ssl/
    megavolts/lego_cli:latest

Notes: The container /opt/lego/ssl/ directory will contain the certificates under /opt/lego/ssl/certificates and keys under /opt/lego/ssl/certificates/accounts make sure to bind it to a specific host directory. See https://go-acme.github.io/lego/usage/cli/general-instructions/⁠

⁠Using Docker Compose

Below is an equivalent example like above but using Docker Compose⁠.

services:
  lego_cli:
    container_name: lego
    image: megavolts/lego_cli:latest
    environment:
      # Lego CLI options
      - LEGO_ENABLE=true
      - LEGO_EMAIL=${LEGO_EMAIL}
      # Domains should be comma separated
      - LEGO_DOMAINS=domain.tld
      # Lego CLI DNS provider
      - LEGO_DNS=porkbun
      - PORKBUN_API_KEY=${PORKBUN_API_KEY}
      - PORKBUN_SECRET_API_KEY=${PORKBUN_SECRET_API_KEY}
      # TLS auto-renewal feature (optional)
      - AUTORENEW=true
    volumes:
      # Directory mapping (bind mount) for certificate/key files
      - ./ssl/:/opt/lego/ssl/
    deploy:
      replicas: 1
      update_config:
        parallelism: 1
      restart_policy:
        condition: unless-stopped

⁠Environment variables

The image provides environment variables support for several Lego CLI⁠ arguments.

Below are the environment variables supported and their default values.

⁠Activation

To activate the environment variables support, set LEGO_ENABLE=true.

• LEGO_ENABLE=false

⁠General options

• LEGO_EMAIL Email used for registration and recovery contact.
• LEGO_DOMAINS Domain or list of domains to include in the certificate. Multiple domains can be specified using a comma separated list (e.g. domain1.tld,subdomain.domain1.tld,domain2.tld)
• LEGO_SERVER=https://acme-v02.api.letsencrypt.org/directory CA hostname (and optionally :port). The server certificate must be trusted in order to avoid further modifications to the client. By default, set to the ACME default server.
• LEGO_CSR Certificate signing request filename, if an external CSR is to be used.
• LEGO_ACCEPT_TOS=true By default, accept the current Let's Encrypt terms of service.
• LEGO_PATH=/opt/lego/ssl Directory to use for storing the data.

⁠Staging

• STAGING=false By setting this flag to true, the staging option is enable, the LEGO_SERVER is override with the default Let's Encrypt staging server (https://acme-staging-v02.api.letsencrypt.org/directory⁠).

⁠Challenge types

• LEGO_HTTP=false By setting this flag to true, use the HTTP-01 challenge to solve challenges. Can be mixed with other types of challenges.
• LEGO_DNS See Lego DNS providers supported https://go-acme.github.io/lego/dns/#dns-providers⁠

⁠Obtain a new certificate

By default, the Lego CLI run subcommand will be executed, which will obtain a new certificate⁠.

⁠Renew existing certificate

To renew a certificate⁠, use the following environment variables instead.

• LEGO_RENEW=false It tells Lego CLI to perform a renewal operation on demand.

This container uses the default behavior of the upcoming Lego v5 to compute dynamically when to renew the certificate based on the lifetime using hte --dynamic option.

⁠Certificate Autorenewal

• AUTORENEW=true By setting this flg to false, disables the autorenewal feature
• AUTORENEW_PERIOD=3 Number of days before the certificate expiration to perform a renewal try.
• AUTORENEW_CRON_SCHEDULE=0 */24* * * * The crontab schedule for the autorenewal checker (default, once every 24 hours)

When the option is AUTORENEW=true then a script will programmatically check the certificate days before the expiration (AUTORENEW_PERIOD) and will perform a renewal try. Note that setting AUTORENEW=true disables LEGO_RENEW should be disabled (false) when using this feature because it refers to the Lego CLI renew operation (subcommand).

⁠Additional arguments

• LEGO_ARGS

Print all available Lego CLI options.

# global options
docker run --rm megavolts/lego_cli -h
# or specific subcommand options
docker run --rm megavolts/lego_cli lego run -h

For more details check out the Lego 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.

⁠Acknowledgements

This work is build upon Jose Quintana⁠'s Let's Encrypt Docker.

Feel free to send some Pull request⁠ or file an issue⁠.

⁠Licenses

⁠License

Unless explicitly stated otherwise, this work is primarily distributed under the terms of both the MIT license⁠ and the Apache License (Version 2.0)⁠.

⁠License for other compoents

• Docker: Apache 2.0⁠
• Lego: MIT License⁠