zima-apps/Apps/caddy-autogen/README.md

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:

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:

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