Skip to content

Caddy automatic HTTPS, end to end

How Caddy provisions, renews, and rotates TLS certificates automatically — the mechanism, the state on disk, and the operational levers an MSP wants on hand.

Caddy’s headline feature is “HTTPS by default” — drop a hostname into a Caddyfile, restart the service, and a Let’s Encrypt certificate appears on disk within seconds. This article unpacks what is actually happening, where the state lives, and the operational levers we keep on hand so the automation never becomes a black box. The audience is anyone running Caddy in front of a real workload who does not want to learn ACME the hard way during a renewal failure.

How to verify

The fast checks. If automatic HTTPS is working, all three return what you expect:

curl -I https://example.com/
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -dates
sudo ls -la /var/lib/caddy/.local/share/caddy/certificates/
sudo journalctl -u caddy --since '24h ago' | grep -iE 'certificate|acme|tls'

The curl should return 200 with strict-transport-security set. The openssl should show Let's Encrypt (or ZeroSSL — Caddy’s secondary issuer) as the issuer and a notAfter date 60–90 days out. The journal should show one issuance per host, no error retries.

What’s happening

Caddy’s automatic HTTPS is three loops running in the same process:

  1. Issuance. When the config loads, Caddy walks every host name in every site block and asks the certificate manager: “do I have a valid cert for this name?” If not, it kicks off an ACME order against the configured issuer (Let’s Encrypt by default, ZeroSSL as fallback). The challenge is HTTP-01 over port 80 by default, TLS-ALPN-01 over port 443 if 80 is unreachable, or DNS-01 if the global config names a DNS provider.

  2. Storage. Issued certificates, private keys, account data, and OCSP staples land under $XDG_DATA_HOME/caddy/ (which for the systemd service resolves to /var/lib/caddy/.local/share/caddy/). The layout is deterministic: certificates/<ca>/<hostname>/<hostname>.crt plus .key and .json metadata. The directory is the source of truth — Caddy reads from it on every reload.

  3. Renewal. A background goroutine wakes every ~10 minutes and inspects every cert. If the cert is within one-third of its lifetime from expiry (so ~30 days for a 90-day Let’s Encrypt cert), Caddy renews. Renewals reuse the existing key by default — set key_type in the global block to force a new key on each renewal if you care about that.

OCSP stapling runs on the same cycle. Caddy fetches the OCSP response on issuance, caches it, refreshes it before expiry, and staples it into the TLS handshake. No extra config needed.

The TLS handshake itself negotiates the safe defaults Caddy ships with: TLS 1.2 and 1.3, modern cipher suites only, X25519 and P-256 curves, no compression, ALPN advertising HTTP/2 and HTTP/3. You can override every one of these in the tls directive — but the defaults pass SSL Labs A+ out of the box.

The mechanism

The Caddyfile that triggers automatic HTTPS is the simplest possible:

{
    email ops@example.com
}

example.com, api.example.com {
    reverse_proxy localhost:3000
}

That is enough. Caddy will:

  • Open port 80 and 443.
  • Issue certs for both hostnames.
  • Redirect HTTP to HTTPS with a 308.
  • Serve HTTPS with HSTS enabled (max-age 31536000).
  • Renew automatically.

If you need to control the issuer order, the ACME endpoint (staging vs production), or the storage backend, the global block grows:

{
    email ops@example.com

    acme_ca https://acme-v02.api.letsencrypt.org/directory
    acme_ca https://acme.zerossl.com/v2/DV90
    acme_eab {
        key_id <eab-key-id>
        mac_key <eab-mac-key>
    }

    storage file_system {
        root /var/lib/caddy
    }
}

For a cluster of Caddy nodes sharing certs, swap the file system storage for Redis, Consul, or S3 — see caddy modules and plugins for the binaries that include those storage backends.

The on-disk layout under /var/lib/caddy/.local/share/caddy/ after issuance:

acme/
  acme-v02.api.letsencrypt.org-directory/
    users/
      <email>/
        <email>.json
        <email>.key
certificates/
  acme-v02.api.letsencrypt.org-directory/
    example.com/
      example.com.crt
      example.com.json
      example.com.key
locks/
ocsp/

The locks/ directory is how Caddy coordinates issuance across multiple instances when the storage backend supports atomic locking. If you run multiple nodes against the same Redis or S3 backend, only one node will perform the ACME exchange — the others read the resulting cert.

Operational notes

  • The first issuance against Let’s Encrypt counts against the per-domain rate limit (currently 50 certs per registered domain per week). Issuing 60 unique subdomains in one push will fail half of them with too many certificates already issued. Stagger or use a wildcard with DNS-01.
  • The renewal goroutine writes to the local storage path; if /var/lib/caddy is on a read-only volume, renewals fail silently — no metric fires, only a journal line. Watch for error: writing key patterns.
  • Caddy will keep retrying a failed ACME order forever. The exponential backoff caps at one hour; an actually-broken DNS record will retry once per hour until you fix it. Set up an alert on caddy_certificates_renewals_failed_total > 0 from the metrics endpoint.
  • The email global directive doubles as the ACME account email and the certificate Subject Alternative Name contact. Without it, Let’s Encrypt registrations use a placeholder address and you receive zero expiry warning emails.
  • Setting auto_https off in the global config disables all of this. Useful when Caddy sits behind another TLS terminator (an upstream load balancer with its own cert) — but you lose HSTS, redirect, and renewal at the same time.
  • The first request after a cold start may take 5–30 seconds while the cert provisions. For SLO-sensitive deployments, pre-warm by issuing the cert on a build host and copying /var/lib/caddy/.local/share/caddy/ into the production volume before first launch.

Stack Harbor runs the certificate state of every Caddy host as monitored infrastructure — the renewal lag, the OCSP cache age, and the storage backend availability are all metrics our pipeline alerts on, not assumptions. If you are running Caddy in front of customer-facing traffic and a renewal failure would page you, this is the kind of automation we put under our Managed Operations practice.