diff --git a/AGENTS.md b/AGENTS.md index 14b209b..be54a77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,3 +91,30 @@ Regler för ``: - `initial`: max 5 ord som beskriver vad som byggs. - `bugfix`: vad som fixas (kort och konkret). - `update`: versionsuppdatering i formen `vX.Y.Z-to-vA.B.C`. + +## 9) Parallellt agentarbete och git-scope + +- När en ny app skapas ska en ny mapp alltid skapas under `Apps//`. +- Flera agenter kan arbeta samtidigt. Fråga alltid innan du skapar ny branch eller byter branch, för att undvika krockar. +- `git add` och `git commit` får endast omfatta filer i den egna appens undermapp under `Apps//`. + +## 10) Verifieringsdokument när app är redo + +När en app bedöms som \"redo\" ska appmappen innehålla en verifieringsfil: + +- `Apps//HOW_TO_VERIFY.md` + +Filen ska vara praktiskt körbar och innehålla: + +- tydliga förutsättningar (miljö, DNS, secrets, beroenden), +- positiva testfall med förväntade resultat, +- minst ett fail-closed/negativt testfall, +- exakta kommandon för att verifiera DNS, nät och TLS, +- en sektion \"data att samla\" för snabb Codex-felsökning. + +Sektionen \"data att samla\" ska minst täcka: + +- versions-/buildinfo (appversion, branch/commit eller zip + checksum), +- relevant konfiguration (med maskade secrets), +- loggar från berörda containers, +- konkreta felobservationer (hostname, tidpunkt, förväntat vs faktiskt beteende). diff --git a/Apps/caddy-autogen/HOW_TO_VERIFY.md b/Apps/caddy-autogen/HOW_TO_VERIFY.md new file mode 100644 index 0000000..d0b5e55 --- /dev/null +++ b/Apps/caddy-autogen/HOW_TO_VERIFY.md @@ -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=` +- `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 `` och `` 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