Certificates

TL;DR

• Main certificate covers all domains in autocert.domains
• Extra certificates can be configured for additional domains
• SNI selection: exact match > wildcard match, main cert > extra cert
• Managed by lego (ACME) with DNS-01; auto-issued and auto-renewed
• Bring your own certificate with provider: local
• Short alias vs FQDN determines how domains match
• match_domains restricts which base domains are valid

Certificates

• Main certificate covers every domain in autocert.domains

• Extra certificates can be added via the extra field for additional domains

• Based on SNI (Server Name Indication) from the client's TLS handshake

  • Exact match > wildcard match (e.g., app.example.com exact beats *.example.com wildcard)
  • Main cert > extra certificates when both match
  • Falls back to main cert if no match

• Issued/managed by lego using ACME, typically Let's Encrypt via DNS-01

• Auto-issue/renew with 1-hour cooldown after failures. Renewal happens when:

  • autocert is enabled but no certs are present
  • The set of autocert.domains no longer matches the loaded certificate
  • The certificate will expire within 30 days

Extra Certificates

• Must specify unique cert_path and key_path (no duplicates)

• Inherit all configuration from the main config (except extra)

• Participate in ACME cycles independently

• Selected via SNI when the client's requested domain matches (exact or wildcard)

• Main certificate takes precedence when both match

Autocert Configuration

1. EAB refers to External Account Binding.

Using Existing SSL Certificate

autocert:
  provider: local
  # path relative to /app
  cert_path: certs/cert.crt
  key_path: certs/priv.key

Autocert with Cloudflare

autocert:
  provider: cloudflare
  email: your-email@example.com
  domains:
    - "*.yourdomain.com"
  options:
    auth_token: your-zone-api-token

Autocert with a Custom Internal CA

You may use internal CA like step-ca for issuing certificates.

Use step-ca as an example:

export ACME_URL=https://acme.internal
# get root certs and save to `certs/roots.pem`
# assume that `certs/` is mounted to `/app/certs` (by default)
curl -k https://${ACME_URL}/roots.pem > certs/roots.pem

autocert:
  provider: custom
  email: your-email@example.com
  domains:
    - "*.yourdomain.com"
  ca_dir_url: https://acme.internal/acme/acme/directory
  ca_certs:
    - certs/roots.pem

EAB

If using EAB (External Account Binding), set eab_kid and eab_hmac in autocert. Also works with custom ACME CAs.

autocert:
  provider: custom
  email: your-email@example.com
  domains:
    - "*.yourdomain.com"
  eab_kid: your-eab-kid
  eab_hmac: base64-encoded-hmac

Multiple Certificates with SNI

Configure multiple certificates for different domains. GoDoxy uses SNI to select the appropriate certificate during TLS handshake.

Example: Multiple certificates with different providers

autocert:
  provider: cloudflare
  email: your-email@example.com
  domains:
    - "*.example.com"
  options:
    auth_token: your-zone-api-token
  extra:
    # Extra cert 1: Same provider, different domain
    - cert_path: certs/other.crt
      key_path: certs/other.key
      domains:
        - "*.other.com"
      # Inherits provider, email, options from main config

    # Extra cert 2: Different provider (custom CA)
    - cert_path: certs/internal.crt
      key_path: certs/internal.key
      provider: custom
      domains:
        - "*.internal.local"
      ca_dir_url: https://ca.internal/acme/directory

    # Extra cert 3: Local/static certificate
    - cert_path: certs/static.crt
      key_path: certs/static.key
      provider: local
      domains:
        - "*.services.internal"
      # Static certificate, no ACME obtain/renew

SNI Selection Behavior:

Based on the example above, certificate selection works as follows:

Selection Precedence:

1. Exact match > wildcard match
2. Main cert > extra certificates when both match
3. Falls back to main cert if no match

Other DNS providers

Check DNS-01 Providers

Troubleshooting

If you encounter issues:

• Set LEGO_DISABLE_CNAME_SUPPORT=1 if your domain has a CNAME record
• Try different DNS resolvers via autocert.resolvers