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