# 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`.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/caddy/

## 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](https://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

1. DNS points the domain at the host's address
2. Caddy accepts HTTPS on 443 and HTTP on 80 (for redirects and ACME)
3. TLS terminates at Caddy
4. Caddy adds forwarding headers and proxies to Uvicorn
5. 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](/docs/technology/http-caching/)).
- One host means one Caddy. There is no second edge in front of it.

## Security and privacy

- TLS everywhere, HSTS on the `www` host, 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](/docs/technology/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](/docs/technology/uvicorn/).
**`www` does not redirect** — The `www` record must resolve to the same host.

## Official references

- [Caddy documentation](https://caddyserver.com/docs/)
- [Automatic HTTPS](https://caddyserver.com/docs/automatic-https)
- [reverse_proxy directive](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy)

## 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.

## Related

- [HTTPS and TLS](https://connectbyjbrh.com/docs/technology/https/)
- [Uvicorn, the ASGI server](https://connectbyjbrh.com/docs/technology/uvicorn/)
- [DNS](https://connectbyjbrh.com/docs/technology/dns/)
- [Amazon Web Services hosting](https://connectbyjbrh.com/docs/technology/aws-hosting/)

## What this page is based on

- `ops/Caddyfile`
- `ops/aws/bootstrap-host.sh`
- https://caddyserver.com/docs/automatic-https
