Joachim Friberg
132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# Caddy AutoGen
|
|
|
|
Caddy AutoGen bygger Caddy-routes "on the fly" från körande containers i ZimaOS/CasaOS.
|
|
|
|
Arkitektur:
|
|
|
|
- `discovery-agent` läser Docker metadata via `socket-proxy`.
|
|
- Endast explicit opt-in exponeras (`LABEL_CADDY_ENABLE=true`).
|
|
- Caddy config laddas dynamiskt via Caddy Admin API (`POST /load`).
|
|
- TLS sker med Let's Encrypt DNS-01 via Cloudflare.
|
|
- Ett enkelt status-UI finns på port `31820` (LAN/private ranges only).
|
|
|
|
## Status-UI (v1)
|
|
|
|
Status-UI visar:
|
|
|
|
- senaste config apply-status,
|
|
- Cloudflare reachability + token-validitet,
|
|
- genererade hosts/routes,
|
|
- om Let's Encrypt-cert verkar finnas för varje host.
|
|
|
|
URL (default):
|
|
|
|
- `http://<zima-lan-ip>:31820/`
|
|
|
|
Obs:
|
|
|
|
- "Hosts" i UI betyder **genererade Caddy-routes**, inte att appen skapar A/CNAME-records i Cloudflare-zonen.
|
|
- Certstatus bygger på Caddys lokala certificate storage och är en praktisk v1-signal.
|
|
|
|
## Säkerhetsmodell
|
|
|
|
- Fail-closed default: om `REQUIRE_CLOUDFLARE=true` och token saknas laddas ingen ny extern config.
|
|
- Ingen auto-exponering av alla portar.
|
|
- Endast HTTP(S)-upstreams stöds i v1.
|
|
- Docker socket exponeras inte direkt till agenten, endast via `socket-proxy` med begränsade endpoint-flaggor.
|
|
- Status-UI är LAN-begränsat (`remote_ip private_ranges`).
|
|
|
|
## Miljövariabler (appnivå)
|
|
|
|
- `BASE_DOMAIN` (krävs), t.ex. `home.example.com`
|
|
- `CLOUDFLARE_API_TOKEN` (krävs i fail-closed läge)
|
|
- `WILDCARD_DOMAIN` (valfri), t.ex. `home.example.com`
|
|
- `REQUIRE_CLOUDFLARE` (default `true`)
|
|
- `ALLOW_INTERNAL_TLS_FALLBACK` (default `false`)
|
|
- `POLL_SECONDS` (default `15`)
|
|
- `STATUS_BIND` (default `0.0.0.0:8089`, intern agent endpoint)
|
|
- `STATUS_UI_PORT` (default `31820`)
|
|
- `CF_VERIFY_URL` (default Cloudflare token verify endpoint)
|
|
|
|
Cloudflare-token bör vara scoped till minsta möjliga rättigheter:
|
|
|
|
- `Zone.Zone:Read`
|
|
- `Zone.DNS:Edit`
|
|
|
|
## Miljövariabler på målcontainers (opt-in)
|
|
|
|
Sätt dessa på varje container som ska exponeras:
|
|
|
|
- `LABEL_CADDY_ENABLE=true`
|
|
- `LABEL_CADDY_TARGET_PORT=<container_tcp_port>`
|
|
|
|
Valfria:
|
|
|
|
- `LABEL_CADDY_HOST=<subdomain-or-fqdn>`
|
|
- `LABEL_CADDY_SCHEME=http|https`
|
|
- `LABEL_CADDY_PATH=/`
|
|
- `LABEL_CADDY_HEALTH_URI=/health`
|
|
|
|
### Exempel (Frigate)
|
|
|
|
För Frigate med portar `5000`, `8554`, `8555`:
|
|
|
|
- Sätt `LABEL_CADDY_ENABLE=true`
|
|
- Sätt `LABEL_CADDY_TARGET_PORT=5000`
|
|
|
|
Då skapas endpoint bara för web UI-porten (`5000`), inte för RTSP/WebRTC-portarna.
|
|
|
|
Konkreta env-vars att sätta på Frigate-containern:
|
|
|
|
```text
|
|
LABEL_CADDY_ENABLE=true
|
|
LABEL_CADDY_TARGET_PORT=5000
|
|
LABEL_CADDY_HOST=frigate
|
|
LABEL_CADDY_SCHEME=http
|
|
LABEL_CADDY_PATH=/
|
|
```
|
|
|
|
## Lokal DNS för split-horizon
|
|
|
|
Rekommenderad stack: **AdGuard Home**.
|
|
|
|
- Skapa lokala records/rewrite för `*.BASE_DOMAIN` och `BASE_DOMAIN` mot ZimaOS-serverns LAN-IP.
|
|
- Behåll samma publika zon i Cloudflare för DNS-01-validering.
|
|
|
|
Alternativ som fungerar bra i ZimaOS:
|
|
|
|
- Technitium DNS (mer avancerad DNS-kontroll)
|
|
- Pi-hole (+ ev. Unbound)
|
|
|
|
## Säkerhetsavvikelser
|
|
|
|
Följande högriskdetaljer är medvetna designval:
|
|
|
|
- Använder Docker API via `socket-proxy` (inte direkt socket i discovery-agent).
|
|
- Caddy måste exponera 80/443 för ingress.
|
|
|
|
Riskreduktion:
|
|
|
|
- socket-proxy endpoint-whitelist (`CONTAINERS`, `EVENTS`, `INFO`, `NETWORKS`, `PING`, `VERSION`)
|
|
- `POST=0`
|
|
- `no-new-privileges`
|
|
- read-only där möjligt
|
|
|
|
## Integrationstester
|
|
|
|
Kör lokala integrationstester för discovery-agenten:
|
|
|
|
```bash
|
|
./Apps/caddy-autogen/tests/run_integration_tests.sh
|
|
```
|
|
|
|
Testerna mockar Docker API-svar och Cloudflare verify och verifierar:
|
|
|
|
- opt-in-regler (endast markerade containers exponeras),
|
|
- säker portselektionslogik (inga media/UDP-portar routas av misstag),
|
|
- fail-closed beteende när Cloudflare-token saknas,
|
|
- status-UI-block i genererad Caddy-konfiguration,
|
|
- cert-matchning mot lokal Caddy certificate storage.
|
|
|
|
För verifiering i riktig ZimaOS-miljö, se `HOW_TO_VERIFY.md` i samma mapp.
|