4.4 KiB
ZitPlane — Troubleshooting and safe diagnostics
Scope: Only describe issues the current source or recorded phase evidence supports. Run #86 verified an isolated disposable backend, but no developer-PC environment or production deployment has been verified.
| Symptom | Known possible cause | Safe next action |
|---|---|---|
docker command not found |
Docker CLI/Desktop was missing on the previously inspected Windows host during P02 | Install supported Docker Engine/Desktop and run only in a local disposable environment; do not treat a source manifest as runtime acceptance |
docker compose config / up fails |
Local machine Docker/config differences or occupied port may differ from validated CI stack | Gitea Run #86 verified isolated portless CI Compose; check environment-specific logs with secrets redacted; do not confuse its portless override with P02 local loopback Compose |
| Admin Console login fails | First-instance bootstrap, Login V2 container/PAT, auth proxy or credentials not validated | Verify local health, first-init logs and policy in a secret-safe environment; do not reinitialize volumes casually |
| Account Portal shows no page | App dependencies are not installed; no Account Portal image, runtime or domain is configured | Complete reviewed lockfile/build/CI and explicit integration phase before troubleshooting live UI |
| Redirect/callback error after future login | OIDC issuer/callback URL, client type/secret, proxy headers, PKCE/state or allowed redirect may mismatch | Compare exact configured origins and registered callback; never weaken checks or wildcard redirects |
Unauthorized on /api/account/me |
Designed result for absent/expired user identity | Authenticate through ZITADEL; if unexpected in a future runtime, inspect token expiry and session trace securely |
| Profile Save button missing | Portal source has read-only fields only | Use permitted ZITADEL self-service (if configured) or wait for an approved custom edit feature |
| MFA/passkey settings not editable in portal | Portal only shows informational cards and a link | Use the identity provider's policy-supported controls; do not paste secrets into support messages |
| Sign-out seems to leave other applications signed in | Portal signOut is portal-local, not federated logout |
Close respective sessions via app/identity provider; global logout requires a future dedicated implementation |
auth.vib.tools / account.vib.tools unavailable |
They are planned hostnames, no production deployment configured | Do not assume DNS/SSL/Coolify service exists; await P07 |
| Login V2 custom source appears unchanged when starting P02 Compose | P02 Compose uses prebuilt official Login UI, not P03 imported code | Later P05 must build and wire custom image after CI and explicit approval |
How to report a safe issue
Include environment (local disposable vs CI vs production), exact phase/commit, which page/action, a redacted error and reproduction conditions. Never publish .env, client secret, passwords, access tokens, cookies, private keys or user data. Link to relevant phase note; record the fix and updated user guidance together.
P05-CI-02 verification and error boundaries
- Prior Account Portal
TS2345atsrc/auth.ts(14,61)in Gitea Run #81 was fixed by verified JWT subject narrowing; Gitea Run #83 Account Portal typecheck/build PASS. - Previous Alpine backend checkout missed Git; Run #83 verified the fix. Run #83 also exposed an occupied shared-runner host TCP 8080. Run #86 verified the portless CI Compose overlay: all four services ready, disposable Postgres restart persistence, ZITADEL ready/OIDC discovery/JWKS and complete CI-only cleanup PASS. This does not prove the separate P02 local PC Compose or real user login.
- A green HIGH/CRITICAL advisory audit gate still allows Moderate findings; the P05-CI-02 registry detail report records IDs/package/fix separately, without package upgrades.
- CI negative access tests do not simulate real login; actual OIDC app registration/authorized login/MFA must receive separate approval.
Known limitations
Account Portal and Login V2 build CI passed in Run #83, disposable backend acceptance passed in Run #86, and dependency lockfiles/workflows exist. Real authenticated OIDC callback/positive session, MFA/passkey, Admin Console human login, production Coolify/TLS/backup and production support remain UNVERIFIED. Preserve the Scope Lock in notes/ and ZITADEL security boundaries.