Frank
c8d7ed65c6
Caddy v2.11.4's caddyfile adapter rejects 'tls { insecure_skip_verify }'
inside transport http (unrecognized subdirective '{') and also rejects
the handler-level form. The working form, verified live against PMS with
a throwaway caddy (200 OK), is the bare token:
reverse_proxy 192.168.0.235:32400 {
transport http {
tls_insecure_skip_verify
}
}
97 lines
5.6 KiB
Markdown
97 lines
5.6 KiB
Markdown
# Caddy
|
|
|
|
Caddy is the single reverse proxy for both hosts. It runs as a container on Dankclaw (192.168.0.143), terminates TLS with real Let's Encrypt certificates, routes hostnames to containers on both hosts, and protects the homepage and sensitive services with HTTP basic auth.
|
|
|
|
**Docs:** https://caddyserver.com/docs
|
|
|
|
## Facts (live inventory)
|
|
|
|
| Item | Value |
|
|
|------|-------|
|
|
| Image | `franksdank/caddy-porkbun:latest` (local build, `dankclaw/caddy/Containerfile`) |
|
|
| Config | `/home/dank/Containers/caddy/Caddyfile` (bind mount, rendered by deploy) |
|
|
| Data | `/home/dank/Containers/caddy/data` (certs) and `.../config` (ACME state) |
|
|
| Ports | 80, 443 on 192.168.0.143 |
|
|
| TLS | Let's Encrypt, DNS-01 via the Porkbun module (one cert per vhost) |
|
|
| Runs on | Dankclaw only — Dankserver has no Caddy |
|
|
|
|
The Caddyfile in git (`dankclaw/Caddyfile`) carries a `REPLACE_WITH_HASH` placeholder. `scripts/deploy.sh` renders the real basicauth hash from the host `.env` (`CADDY_BASICAUTH_HASH`) into the mounted path before `up`. See [[Deployment Flow]].
|
|
|
|
## The porkbun image
|
|
|
|
Stock Caddy cannot solve the ACME challenge because the router exposes no inbound port 80/443. The local image adds the `github.com/caddy-dns/porkbun` module, which answers the DNS-01 challenge by creating and deleting a `_acme-challenge` TXT record through the Porkbun API. No inbound port is needed. Rebuild only when Caddy or the module needs an update:
|
|
|
|
```
|
|
podman build -t franksdank/caddy-porkbun:latest -f dankclaw/caddy/Containerfile .
|
|
```
|
|
|
|
The Caddyfile references the credentials through the environment:
|
|
|
|
```
|
|
acme_dns porkbun {
|
|
api_key {env.PORKBUN_API_KEY}
|
|
api_secret_key {env.PORKBUN_API_SECRET_KEY}
|
|
}
|
|
```
|
|
|
|
compose passes both variables from the host `.env`. Keep the real keys in `.env` only; `.env.example` holds placeholders. The Porkbun account holds only `franksdank.cloud`.
|
|
|
|
## Vhost map
|
|
|
|
Every vhost uses the flat `franksdank.cloud` convention. The full list lives in `dankclaw/Caddyfile`. Routing by host:
|
|
|
|
| Upstream | Reach |
|
|
|----------|-------|
|
|
| Dankclaw services (compose network) | by container name, e.g. `comfyui:8188` |
|
|
| Dankclaw quadlet services | by published LAN port, e.g. `192.168.0.143:3000` (Gitea) |
|
|
| Dankserver services | by published LAN port, e.g. `192.168.0.235:8085` (RomM) |
|
|
|
|
The bare-IP catch-all `:80` 302-redirects to `https://dankclaw.franksdank.cloud/`. The legacy name `dankserver.franksdank.cloud` 302-redirects there too. `plex.franksdank.casa` is the only plain-HTTP vhost; it cannot get a DNS-01 cert because `franksdank.casa` is not in the Porkbun account. The canonical Plex name is `plex.franksdank.cloud`. Both Plex vhosts dial PMS **over TLS upstream** (`transport http { tls_insecure_skip_verify }` — in this Caddy build the flag is a bare token inside the transport block, not a `tls {}` sub-block): PMS 1.43.x silently closes plain-HTTP connections from non-loopback sources (diagnosed 2026-08-26 — it accepts, reads the request, and FINs without responding), which surfaced here as an empty-body 502 (blank page in browsers). `insecure_skip_verify` applies only to this pinned-LAN hop (PMS serves a self-signed cert); client-facing Let's Encrypt TLS is unchanged. The Plex web UI is at `/web/`; `/` returns the XML `MediaContainer` index.
|
|
|
|
## Basic auth
|
|
|
|
The Caddyfile in git carries a **bare** placeholder; deploy.sh substitutes the **full** hash from the host `.env` (`CADDY_BASICAUTH_HASH`):
|
|
|
|
```
|
|
chat.franksdank.cloud {
|
|
basicauth {
|
|
dank REPLACE_WITH_HASH
|
|
}
|
|
reverse_proxy 192.168.0.143:3005
|
|
}
|
|
```
|
|
|
|
After rendering, the line reads `dank $2a$14$xxxx…` (one complete hash). Do not put a `$2a$14$` prefix in the template: it would render a double-prefixed, invalid hash (2026-08-22 incident — every basicauth vhost returned 401 for every password). `tests/deployment_flow.bats` pins the render contract.
|
|
|
|
The homepage (and SearXNG, Hermes, Prometheus, RomM, Copyparty) use `forward_auth` (Authentik SSO) rather than basicauth; see [[Homepage]] and [[Authentik]]. The basicauth hash above is still rendered for the vhosts that keep it (Grafana, Pi-hole).
|
|
|
|
## Operations
|
|
|
|
Validate before a reload:
|
|
|
|
```
|
|
caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
|
|
```
|
|
|
|
The admin endpoint stays on (loopback-only, unpublished port), so a Caddyfile change hot-reloads within seconds via the file watcher. deploy.sh also issues an explicit reload after rendering. Manual reload from the host:
|
|
|
|
```
|
|
podman exec caddy caddy reload --config /etc/caddy/Caddyfile --adapter caddyfile
|
|
```
|
|
|
|
Certificates and ACME state live in the caddy data volume. Back it up with the stack. Each vhost owns one certificate; renewals are automatic and also use DNS-01.
|
|
|
|
## Gotchas
|
|
|
|
- `admin off` disables the config file watcher: rendered changes then sit on disk while Caddy serves its stale in-memory config until the container is recreated, and nothing logs an error (2026-08-22: a broken basicauth hash survived several deploys this way). `tests/caddyfile.bats` forbids `admin off`.
|
|
- The basicauth template must stay a bare `REPLACE_WITH_HASH` token (no `$2a$14$` prefix) — the rendered value is the complete hash. A double prefix silently rejects every password with 401; no Caddy error is logged.
|
|
- A new vhost needs three things: a Pi-hole `addn-hosts` line, a Porkbun A record, and the Caddyfile block. See [[LAN-DNS]].
|
|
- The G36 has no NAT loopback, so LAN clients must resolve the name to the LAN IP. That is the Pi-hole role in [[LAN-DNS]].
|
|
- Caddy serves HTTPS on 443 and HTTP on 80 (redirects). The router needs no 80/443 port forward for LAN use.
|
|
|
|
## See Also
|
|
|
|
- [[LAN-DNS]] — how names resolve on the LAN and WAN
|
|
- [[Network Architecture]] — topology, access policy
|
|
- [[Homepage]]
|
|
- [[Dankclaw Stack]] |