Caddy web server
Caddy is the only program on Connect's host that listens to the internet for the website. It obtains and renews the TLS certificates automatically, redirects www to the bare domain, compresses responses and forwards each request to the application on the loopback interface. The whole configuration is a few lines in ops/Caddyfile.
What it is#
Caddy is an open-source web server written in Go, first released in 2015 by Matt Holt. Its distinguishing feature is automatic HTTPS: it obtains and renews certificates from ACME authorities such as Let's Encrypt without configuration.
The Caddyfile is its compact configuration format. Connect's version names two sites: the www host, which sets HSTS and redirects permanently, and the main domain, which compresses with zstd or gzip and reverse-proxies to 127.0.0.1:8420.
- Category
- Web server and reverse proxy
- Configuration
ops/Caddyfile- Installed by
ops/aws/bootstrap-host.sh(Ubuntu package)- Official site
- caddyserver.com
Where Connect uses it#
| Place in Connect | What it does there |
|---|---|
www.connectbyjbrh.com | Sets Strict-Transport-Security and redirects to the bare domain |
connectbyjbrh.com | encode zstd gzip, then reverse_proxy 127.0.0.1:8420 |
| Certificates | Issued and renewed automatically through ACME |
How it connects#
- DNS points the domain at the host's address
- Caddy accepts HTTPS on 443 and HTTP on 80 (for redirects and ACME)
- TLS terminates at Caddy
- Caddy adds forwarding headers and proxies to Uvicorn
- Responses are compressed on the way back
Benefits and limits#
What it gives Connect:
- Certificates cannot quietly expire. Renewal is automatic and early.
- A short configuration is easy to review: there is little to get wrong.
- HTTP/2 and HTTP/3 support come by default.
Where it stops, and what Connect does about it:
- Automatic issuance needs ports 80 or 443 reachable and DNS correct. A DNS change before the address is ready makes issuance fail until it is.
- Caddy does not cache application responses in this configuration. Cache headers come from the application (HTTP caching).
- One host means one Caddy. There is no second edge in front of it.
Security and privacy#
- TLS everywhere, HSTS on the
wwwhost, and the application reachable only through Caddy. - The application trusts forwarding headers only from 127.0.0.1, which is Caddy.
- Security headers such as the Content Security Policy are set by the application, so they are the same in development and production (CSP).
Licence, cost and versions#
| Question | Answer |
|---|---|
| Licence | Apache-2.0 |
| Cost | None. Certificates from Let's Encrypt are free |
| Version | The Ubuntu package installed by the bootstrap script. The repository does not pin one |
| Compatibility | Caddy 2 Caddyfile syntax |
Troubleshooting#
- Browser shows a certificate error after a move
- DNS still points at the old address, or port 80 or 443 is blocked, so the ACME challenge fails. Check Caddy's journal.
- 502 Bad Gateway
- Caddy is up but the application is not answering on 8420. See Uvicorn.
wwwdoes not redirect- The
wwwrecord must resolve to the same host.
Official references#
Questions#
Who issues Connect's TLS certificate?
An ACME certificate authority, obtained and renewed by Caddy automatically. By default that is Let's Encrypt, with ZeroSSL as Caddy's fallback.
Does Caddy serve the static files?
No. In this configuration everything is proxied to the application, which serves webapp/ with its own cache headers.