Add caddy-autogen verification guide and readiness policy

2026-03-18 21:20:38 +01:00
parent abb9f3319b
commit 2fddde0129
3 changed files with 150 additions and 0 deletions
@@ -0,0 +1,121 @@
+# HOW_TO_VERIFY (Caddy AutoGen)
+
+Denna fil beskriver hur du verifierar appen i en riktig ZimaOS-miljö och vilken data som behövs vid felsökning.
+
+## 1) Förutsättningar
+
+- ZimaOS med appen `caddy-autogen` installerad.
+- En fungerande domän i Cloudflare (publik zon).
+- AdGuard Home (eller annan lokal DNS) i LAN.
+- Cloudflare API-token med minst:
+  - `Zone.Zone:Read`
+  - `Zone.DNS:Edit`
+- Minst en målcontainer med web UI-port.
+
+## 2) Grundkonfiguration
+
+Sätt appvariabler i `caddy-autogen`:
+
+- `BASE_DOMAIN=home.example.com`
+- `WILDCARD_DOMAIN=home.example.com`
+- `CLOUDFLARE_API_TOKEN=<token>`
+- `REQUIRE_CLOUDFLARE=true`
+- `ALLOW_INTERNAL_TLS_FALLBACK=false`
+
+Konfigurera lokal DNS (AdGuard Home):
+
+- `A`/rewrite för `*.home.example.com` -> ZimaOS LAN-IP
+- `A`/rewrite för `home.example.com` -> ZimaOS LAN-IP
+
+## 3) Positivt test: endpoint skapas korrekt
+
+Exempel med Frigate (web UI på 5000):
+
+Sätt env-vars på Frigate-containern:
+
+```text
+LABEL_CADDY_ENABLE=true
+LABEL_CADDY_TARGET_PORT=5000
+LABEL_CADDY_HOST=frigate
+LABEL_CADDY_SCHEME=http
+LABEL_CADDY_PATH=/
+```
+
+Verifiera:
+
+1. Vänta 15-30 sekunder (default polling).
+2. Öppna `https://frigate.home.example.com`.
+3. Kontrollera att sidan svarar med giltigt certifikat.
+4. Kontrollera att media-portar (8554/8555) inte blivit egna hostnamn/endpoints.
+
+Förväntat resultat:
+
+- Endpoint finns för web UI.
+- Certifikat utfärdas via Let's Encrypt DNS-01.
+- Endast explicit målport routas.
+
+## 4) Negativt test: fail-closed
+
+Scenario A, ingen opt-in:
+
+1. Ta bort `LABEL_CADDY_ENABLE=true` från målcontainern.
+2. Vänta en polling-cykel.
+3. Kontrollera att endpointen försvinner/slutar routas.
+
+Scenario B, saknad Cloudflare-token:
+
+1. Sätt `REQUIRE_CLOUDFLARE=true`.
+2. Ta bort eller ogiltiggör `CLOUDFLARE_API_TOKEN`.
+3. Verifiera att ingen ny extern route publiceras.
+
+Förväntat resultat:
+
+- Appen exponerar inte tjänster oavsiktligt.
+- Loggar visar tydligt fel kring token/Cloudflare.
+
+## 5) Kommandon för snabb verifiering
+
+Byt `<domain>` och `<host>` enligt din miljö.
+
+```bash
+nslookup frigate.home.example.com
+curl -vk https://frigate.home.example.com/
+openssl s_client -connect frigate.home.example.com:443 -servername frigate.home.example.com </dev/null
+```
+
+Containerloggar:
+
+```bash
+docker logs --tail 200 caddy-autogen-discovery
+docker logs --tail 200 caddy-autogen
+docker logs --tail 200 caddy-autogen-socket-proxy
+```
+
+## 6) Data att samla innan du ber en Codex-agent om hjälp
+
+Samla detta först. Det kortar felsökningstiden avsevärt.
+
+1. Miljöinfo:
+- ZimaOS-version.
+- Appens branch/commit eller zip-artefakt (filnamn + SHA256).
+- Vilken DNS-server som används lokalt.
+
+2. Appkonfiguration:
+- Alla app-env-vars för `caddy-autogen` (maska secrets).
+- Målcontainerns `LABEL_CADDY_*`-env-vars.
+- Målcontainerns publicerade portar.
+
+3. Nät/TLS-bevis:
+- `nslookup`-svar från en LAN-klient.
+- `curl -vk` output mot endpoint.
+- `openssl s_client` sammanfattning av cert/issuer.
+
+4. Loggar:
+- Senaste 200 rader från `caddy-autogen-discovery`.
+- Senaste 200 rader från `caddy-autogen`.
+- Senaste 200 rader från `caddy-autogen-socket-proxy`.
+
+5. Problemdefinition:
+- Exakt hostname som inte fungerar.
+- Förväntat beteende och faktiskt beteende.
+- Tidpunkt när felet observerades.
@@ -102,3 +102,5 @@ 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.
+
+För verifiering i riktig ZimaOS-miljö, se `HOW_TO_VERIFY.md` i samma mapp.