Caddy HTTPS Configuration

Automatic HTTPS is the feature that distinguishes Caddy from every other web server: you write a domain name, and Caddy obtains a publicly trusted certificate for it, redirects plain HTTP to HTTPS, and renews the certificate before it expires, with no cron job and no certificate agent. By the end of this page you will be able to explain exactly what Caddy does on your behalf, force a specific issuer or protocol version, issue wildcard certificates through the DNS challenge, serve private hostnames with Caddy’s internal certificate authority, and present a certificate you obtained yourself.

1. What Automatic HTTPS does

For every public domain name in the configuration, Caddy runs this sequence:

  1. Bind the listeners. Caddy opens port 443, and also port 80 when it may need to answer an HTTP challenge.
  2. Create or reuse an ACME account. The account is tied to the email address you configure and is stored so that later renewals reuse it.
  3. Solve a challenge. By default this is the HTTP-01 challenge, where a token is published at the well-known ACME path on port 80. The TLS-ALPN-01 challenge travels over the TLS handshake on port 443 instead.
  4. Obtain and install the certificate. The certificate and private key are written to the data directory and loaded into the shared certificate cache, where any site whose names they cover can use them.
  5. Renew before expiry. Caddy scans managed certificates on a schedule and renews them early enough that an unlucky restart never serves an expired certificate.

If the domain does not resolve to this host, or if port 80 is unreachable from the internet, step 3 fails and issuance is retried with backoff. The reason for every failure is written to the Caddy log.

2. The default behaviour

A site block with a bare domain name is enough.

example.com {
	respond "secure" 200
}

That single block gives you a trusted certificate, HTTPS on port 443, and a redirect from port 80. The redirect server is a separate minimal listener that answers only the ACME challenge path and the redirect, which keeps the plain-HTTP surface small.

To keep certificate management but drop the redirect, use the auto_https global option. Its values are off, disable_redirects, and disable_certs. Note that auto_https off does not turn off HTTPS: it only stops certificate automation and the redirect, so an http:// site address is still required to serve plain traffic.

3. The tls directive

The tls directive is where you override any part of that default. It accepts an optional argument plus a block of subdirectives.

example.com {
	tls admin@example.com {
		protocols tls1.2 tls1.3
		key_type p256
	}
	respond "secure" 200
}
SubdirectivePurpose
protocolsThe minimum and maximum TLS versions. Caddy defaults to TLS 1.2 and 1.3
ciphers, curvesCipher suites and key-exchange groups, listed in preference order
key_typeThe private key algorithm: ed25519, p256, p384, rsa2048, or rsa4096
alpnThe application protocols advertised during the handshake, such as h2
client_authMutual TLS, described in section 7
issuerA named certificate issuer with its own configuration
dnsThe DNS challenge provider, described in section 5

Caddy’s defaults are deliberately conservative and are recommended for almost every deployment. Change them only with a specific reason, and pin values explicitly if a compliance rule requires them to stay constant across upgrades.

4. Choosing an issuer

By default Caddy tries the built-in ACME issuers, which reach both Let’s Encrypt and ZeroSSL. Choose the staging endpoint while testing, because it does not share the rate limits of the production endpoint.

{
	email admin@example.com
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

The cert_issuer global option configures issuers in more detail and may be repeated so several are tried in order. Some certificate authorities also require External Account Binding, configured with the acme_eab global option, which takes a key_id and a mac_key.

5. Wildcard certificates and the DNS challenge

The HTTP challenge can only prove control of one hostname at a time, so it cannot issue a wildcard. A wildcard certificate requires the DNS-01 challenge, in which Caddy creates a TXT record under _acme-challenge and asks the DNS provider to publish it. That needs API access to your DNS zone, so it requires a Caddy build that includes a DNS provider module.

xcaddy build --with github.com/caddy-dns/cloudflare

With that module compiled in, the configuration looks like this:

example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
	respond "wildcard ready" 200
}

The env. prefix reads the value from an environment variable, so the API token never has to be written into the Caddyfile. Give the token the narrowest scope your DNS provider supports: permission to edit TXT records in the one zone, and nothing else.

6. Internal certificates for private names

Names that a public CA cannot validate, such as service.internal or a bare hostname, get a certificate from Caddy’s own local certificate authority.

service.internal {
	tls internal
	respond "private" 200
}

The root certificate of that authority lives in the data directory, usually at ~/.local/share/caddy/pki/authorities/local/root.crt. Distribute it to the clients that must trust it, or they will see a certificate warning. The caddy trust and caddy untrust subcommands manage the copy in the operating system trust store.

7. Mutual TLS

To require a client certificate, configure client_auth inside the tls block.

example.com {
	tls {
		client_auth {
			mode require_and_verify
			trust_pool file {
				pem_files /etc/caddy/client-ca.pem
			}
		}
	}
	respond "mutual tls" 200
}

The mode values are request, require, verify_if_given, and require_and_verify. The last is the strictest: the client must present a certificate and it must chain to a certificate in the trust pool.

8. On-demand TLS

On-demand issuance lets Caddy obtain a certificate the first time an unknown hostname is requested, which suits a large set of customer subdomains. Because it lets an unauthenticated client trigger issuance, Caddy requires an ask endpoint that decides whether a name is allowed.

{
	on_demand_tls {
		ask http://localhost:9000/allowed
	}
}

customer-1.example.com {
	tls {
		on_demand
	}
	respond "on demand" 200
}

The ask endpoint receives the hostname as a query parameter and must return a 2xx status to approve issuance. Treat it as a security boundary, not a formality: without it, anyone who can reach your server can make it issue certificates for arbitrary names.

9. Bringing your own certificate

If you already have a certificate, load it directly.

example.com {
	tls /etc/caddy/certs/example.com.pem /etc/caddy/certs/example.com.key
	respond "custom cert" 200
}

Both files are required and both must be PEM encoded. Loaded certificates join the same shared cache as managed ones, so they are reused by any other site whose names they cover.

10. Renewal, storage, and backup

Certificates and keys live under the data directory, by default ~/.local/share/caddy for the account that runs Caddy. Back that directory up, because losing it means losing both your ACME account and your private keys. Caddy can export and import its storage, which is useful when migrating between hosts.

caddy storage export --config /etc/caddy/Caddyfile --output caddy-data.tar.gz
caddy storage import --config /etc/caddy/Caddyfile --input caddy-data.tar.gz

11. Troubleshooting

SymptomLikely causeWhat to check
Issuance reports that the host is unknownThe name does not resolve to this machineConfirm the A and AAAA records
The HTTP challenge times outPort 80 is blocked or redirected elsewhereCheck the firewall and any upstream proxy
Wildcard issuance failsThe DNS provider module is not compiled inRun caddy list-modules and look for the DNS module
Renewals fail after a DNS changeThe provider API token expiredRotate the token and reload Caddy
automatic httpsacmewildcard certificateinternal ca

Approach:

The requirement is a public site that serves HTTPS with one certificate covering the apex domain and every subdomain, plus a private service that needs TLS without a public certificate. The apex and the subdomains share one wildcard certificate, issued through the DNS challenge because the HTTP challenge cannot prove control of an unknown name. The private service is a separate problem and gets a certificate from the local authority.

Steps:

  1. Decide on the challenge. The DNS challenge is required for a wildcard, so build Caddy with xcaddy build --with for the provider that holds the zone.
  2. Give the DNS provider a token limited to editing TXT records in that one zone, and pass it through an environment variable rather than writing it into the Caddyfile.
  3. Declare the apex name and the wildcard name in the same site block, so one certificate covers both and both names are actually served.
  4. Keep the ACME contact address in the global options block, so that one account is registered rather than one per site.
  5. Use the staging endpoint of the certificate authority while testing, because production endpoints have strict rate limits that a broken configuration can exhaust.
  6. For the private service, use tls internal and distribute the local root certificate to the clients that must trust it.
  7. Validate, reload, and confirm the chain from outside with openssl s_client or a browser.

Answer:

The configuration is:

{
	email admin@example.com
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

example.com, *.example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
	root * /srv/www
	file_server
}

service.internal {
	tls internal
	respond "private service" 200
}

The result is one certificate covering example.com and every subdomain beneath it, obtained and renewed automatically through the DNS challenge, and a separate certificate for service.internal signed by Caddy’s local authority. After switching acme_ca back to the production endpoint, caddy validate reports the configuration as valid, caddy reload applies it, and openssl s_client -connect example.com:443 -servername example.com shows a chain whose certificate covers both the apex and the wildcard.

Found an issue with this content?

Tell us what could be improved.