Skip to content

Caddy: HTTP-01 vs DNS-01 Certificates

A common self-hosting trap, worth its own page. caddy gets TLS certificates via an ACME challenge, and which challenge you use determines whether you need extra setup.

HTTP-01 (the default — use this)

  • The stock caddy:2-alpine image issues a separate certificate per subdomain via the HTTP-01 challenge, automatically, on first request.
  • No DNS API token, no custom build, nothing to configure.
  • Smaller blast radius: one compromised cert ≠ every subdomain.
  • Requirement: port 80 reachable, and the subdomain must resolve to the box (wildcard DNS makes new subdomains resolve with no DNS change).

DNS-01 (opt-in, only if you need a wildcard cert)

  • Required to issue a single wildcard certificate (*.domain).
  • The stock image cannot do it — you must build a custom Caddy (xcaddy) bundling a DNS-provider module and supply a scoped API token (that one zone only, never the global key).
  • More moving parts; only worth it for specific needs.

The critical distinction

  • Wildcard DNS record (*.domain → IP) = resolution convenience. Works perfectly with HTTP-01. This is what the stack-sovereignty-box uses.
  • Wildcard certificate = one cert for all subdomains, needs DNS-01. Different thing. Not needed here.

Behind Cloudflare, set DNS records to DNS-only (grey cloud) or HTTP-01 fails — the #1 cert pitfall.