Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Wildcard certs with DNS-01

Issue a *.example.com certificate by proving control of the domain through a DNS TXT record instead of an HTTP path.

Why wildcards need DNS-01

A wildcard name has no single host the CA can reach, so it cannot use the challenge that --tls acme runs. DNS-01 is the only ACME challenge that authorizes a wildcard: the CA gives you a token, you publish it as an _acme-challenge TXT record, and the CA validates the record — not a path on your server. To publish that record without hand-editing your zone, boatramp drives a managed DNS provider through its API.

Issue the certificate

Set the provider’s credentials in the environment, then start serve with --tls acme-dns. This example uses Cloudflare:

export CLOUDFLARE_ZONE_ID=… CLOUDFLARE_API_TOKEN=…
boatramp serve --tls acme-dns \
  --acme-domain example.com \
  --acme-dns-provider cloudflare

acme-dns: cloudflare provider ready
acme: authorizing example.com, *.example.com via dns-01
acme: published _acme-challenge.example.com TXT, waiting for propagation
acme: certificate issued (expires 2026-10-07)
serving https://0.0.0.0:8080

--acme-domain covers both the apex and its wildcard. Repeat the flag for more domains.

The ten built-in providers are the same set the DNS automation uses — cloudflare, route53, oci, digitalocean, hetzner, ns1, dnsimple, gcp-dns, azure-dns, and akamai — each reading its credentials from provider-specific environment variables. For the full provider-by-variable table see DNS providers & credentials; for pointing custom domains at your server see Automate DNS with a provider.

Add preview subdomains

To serve by-id preview deployments over HTTPS, add --acme-wildcard-preview. It issues *.deploy.<domain> alongside the primary wildcard:

boatramp serve --tls acme-dns \
  --acme-domain example.com --acme-dns-provider cloudflare \
  --acme-wildcard-preview

acme: authorizing *.example.com, *.deploy.example.com via dns-01
acme: certificate issued (expires 2026-10-07)

Publish the TXT record by hand

Without a provider account, use the default manual provider. boatramp prints the record and waits for you to add it:

boatramp serve --tls acme-dns --acme-domain example.com --acme-dns-provider manual

acme: add this DNS record, then continue:
  _acme-challenge.example.com  TXT  "3P1eF9…kQ"
acme: certificate issued (expires 2026-10-07)

Reference