Learning Caddy - Automatic HTTPS Magic

#Introduction

This is the feature that made Caddy famous: automatic HTTPS. You simply write a domain name in the Caddyfile, and Caddy obtains the certificate, installs it, secures the connection, and renews it automatically before it expires. No certificate files to manage by hand.

Episode 7 opens up the mechanism behind that magic: the ACME protocol, Let's Encrypt integration, the validation and issuance flow, the automatic renewal process, certificate storage, the pre-requisites that must be met, and the three challenge types available.

This understanding isn't just theory — when automatic HTTPS fails (for example, DNS doesn't point to your server yet), you need to know where the problem is. This episode gives you the ability to fix that kind of problem yourself.

#How Automatic HTTPS Works

#The ACME Protocol and Let's Encrypt

ACME (Automatic Certificate Management Environment) is a standard protocol (RFC 8555) that lets a CA — such as Let's Encrypt — issue certificates automatically. Caddy is a perfect built-in ACME client:

1. You write a public domain in the Caddyfile.
2. Caddy requests issuance from Let's Encrypt.
3. Caddy proves domain ownership through a challenge.
4. The CA issues the certificate, and Caddy installs it immediately.
5. Caddy stores the certificate in storage for reuse.
6. Before expiry, Caddy renews automatically.

All these steps happen with zero extra configuration.

#Automatic HTTPS Pre-requisites

Automatic HTTPS only works if the pre-requisites are met:

• A public domain name — not an IP or localhost.
• DNS already points to the server where Caddy runs.
• Ports 80 and 443 are open — required for challenges.
• An email address is optional for notifications (via the email global option).

If the pre-requisites fail, Caddy still runs — but with an error message in the logs and no certificate. Check these pre-requisites first when troubleshooting.

#Activation and Automatic Behavior

#Triggered by a Domain Name

Caddy enables automatic HTTPS only for public domain names. Writing:

contoh.example.com {
    root * /var/www
    file_server
}

When caddy run is executed, Caddy immediately processes issuance for contoh.example.com with no other command.

#Automatic HTTP-to-HTTPS Redirect

Caddy also handles HTTP-to-HTTPS redirection automatically. Sites served on port 80 will redirect all requests to the HTTPS version — with no extra redir block.

#OCSP Stapling and Certificate Transparency

Two security features handled automatically:

• OCSP stapling: the certificate's validity status is attached to the handshake, speeding up browser verification.
• Certificate transparency: a public log of all issued certificates, monitored by the CA.

Both are production details Caddy handles without your intervention.

#Certificate Storage

#Default Location and Reuse

Certificates are stored in the storage layer, by default at $XDG_DATA_HOME/caddy on Linux. Any domain already processed will reuse a certificate from storage if it's still valid — Caddy won't submit unnecessary re-issuance requests.

#Other Storage Backends

Storage can be moved to another backend via JSON configuration or global options:

{
    storage file_system /var/lib/caddy-data
}
 
example.com {
    root * /var/www
    file_server
}

On a cluster with many instances, shared storage (for example Redis or S3 via a plugin) keeps each instance from requesting the same certificate. Backing up storage is part of disaster recovery, which we'll cover in episode 30.

#The Renewal Process

#Renewal 30 Days Before Expiry

Let's Encrypt certificates are valid for 90 days. Caddy begins renewing 30 days before expiry, in the background, with no downtime. If renewal fails, Caddy retries with backoff and writes the error to the logs.

#Zero Downtime

Because Caddy manages the old and new certificates simultaneously, ongoing connections aren't interrupted. Once the new certificate is ready, Caddy swaps it seamlessly.

#ACME Challenge Types

#HTTP-01, TLS-ALPN-01, and DNS-01

Caddy supports three ways to prove domain ownership:

• HTTP-01 (default): Caddy serves a token file at a specific path over port 80; the CA verifies via HTTP. Requires port 80 to be open.
• TLS-ALPN-01: verification via a TLS handshake on port 443 with a special protocol. Requires port 443 to be open.
• DNS-01: verification via a DNS TXT record; the only way to obtain a wildcard certificate. Requires DNS provider credentials — covered in episode 9.

Caddy picks the best challenge automatically. The logs show which challenge was used:

caddy run --config Caddyfile

If you see challenge succeeded in the logs, issuance was successful. Running caddy run --config Caddyfile in the foreground shows all ACME details live — useful for debugging.

#Conclusion

Episode 7 revealed the mechanics behind Caddy's automatic HTTPS: the ACME protocol with Let's Encrypt, the domain name and port 80/443 pre-requisites, activation automatically triggered by domain names, certificate storage that can be moved, renewal 30 days before expiry without downtime, and the three challenge types.

Key takeaways:

• Automatic HTTPS works for public domain names, not IPs or localhost.
• Caddy is a built-in ACME client; there's no manual issuance configuration.
• Pre-requisites: DNS points to the server and ports 80/443 are open.
• HTTP-to-HTTPS redirects are handled automatically.
• Renewal starts 30 days before expiry without downtime.
• HTTP-01 is default, TLS-ALPN-01 is an alternative, DNS-01 is for wildcards.

In the next episode, episode 8, we'll configure TLS manually: the tls directive, protocol and cipher suite options, disabling automatic HTTPS for development, other certificate sources like ZeroSSL and custom ACME, and HTTPS enforcement with HSTS. You'll be able to control TLS down to the smallest detail.