Joachim Friberg
105 lines
2.9 KiB
Markdown
105 lines
2.9 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.
|
|
|
|
## 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.
|
|
|
|
## 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`)
|
|
|
|
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 Caddy `/load`-anrop 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.
|