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

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: status-UI + endpoint

1. Vänta 15-30 sekunder (default polling).
2. Öppna http://<zima-lan-ip>:31820/.
3. Verifiera i UI:
   • Caddy Apply = OK
   • Cloudflare Reachability = OK
   • Cloudflare Token = OK
   • minst en route visas under Generated Hosts.
4. Öppna en exponerad host, t.ex. https://frigate.home.example.com.

Förväntat resultat:

• UI laddar och visar aktuell status.
• Endpoint finns för web UI-hosten.
• Certifikat utfärdas via Let's Encrypt DNS-01.

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. Verifiera i status-UI att routen försvinner.

Scenario B, saknad/ogiltig Cloudflare-token:

1. Sätt REQUIRE_CLOUDFLARE=true.
2. Ta bort eller ogiltiggör CLOUDFLARE_API_TOKEN.
3. Verifiera i status-UI att Cloudflare Token inte är OK.
4. Verifiera att ingen ny extern route publiceras.

Förväntat resultat:

• Appen exponerar inte tjänster oavsiktligt.
• Loggar visar tydligt token/Cloudflare-relaterat fel.

5) Kommandon för snabb verifiering

Byt <domain>, <host> och <zima-lan-ip> enligt din miljö.

curl -sS http://<zima-lan-ip>:31820/status.json | jq .
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:

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:

• curl -sS http://<zima-lan-ip>:31820/status.json | jq ..
• 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.