25 lines
3.3 KiB
Markdown
25 lines
3.3 KiB
Markdown
# ZitPlane — Troubleshooting and safe diagnostics
|
|||
|
|
|
||
|
|
**Scope:** Only describe issues the current source or recorded phase evidence supports. No live environment 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 | Dev Compose, h2c proxy, dependencies and image pulls were never integration-tested | Review Compose output after an approved isolated CI/dev verification, without revealing secrets; inspect P02 evidence |
|
||
|
|
| 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.
|
||
|
|
|
||
|
|
## Known limitations
|
||
|
|
|
||
|
|
No live integration verification, Account Portal lockfile, CI pipeline, Coolify production deployment, tested authentication redirects or production support guarantees exist as of P04. Before adding any diagnostic workaround, consult the Scope Lock in `notes/` and preserve ZITADEL's security boundaries.
|