# ZitPlane — Development & Deployment Setup Guide **State:** This is a guide to the **current source and planned integration gates**, not proof a live install is available. No public Coolify deployment or Gitea Actions CI exists at P04. ## System pieces - Official Go ZITADEL backend v4.20.4 (Docker image), PostgreSQL 17.10 and Traefik 3.7.7 configured in `deployment/docker/compose.backend.dev.yaml`. - Prebuilt official ZITADEL Login V2 image for that **local-only Compose**. - Imported, unchanged official Login V2 Next.js source under `auth/ui/v2/` (not wired to Compose). - Next.js Account Portal source under `users/ui/` (not started or wired to Compose). ## Requirements for optional local development (future; do not use production user data) - Windows/macOS/Linux host with a supported **Docker engine + Docker Compose** (Docker Desktop with Linux containers on Windows). - Git, Python 3.10+ for P02 `dev.py`. - Account Portal requires Node.js meeting `users/ui/package.json` engine constraint (Node 22+) and dependencies **after a reviewed lockfile is created**. - Login V2 requires its own upstream Node/pnpm/Nx toolchain; exact frozen-install compatibility has **not** been established. - Local loopback TCP 8080 for the development ZITADEL proxy. Account Portal intended local port 3001 after a dev integration step. ## P02 local-only bootstrap commands The `core/backend/zitadel/README.md` is the authoritative current helper guide. The following commands are **instructions only** (not executed in this documentation task): ```powershell cd C:\Users\Administrator\Desktop\Projects\ZitPlane py core/backend/zitadel/dev.py init py core/backend/zitadel/dev.py config py core/backend/zitadel/dev.py up py core/backend/zitadel/dev.py check py core/backend/zitadel/dev.py ps py core/backend/zitadel/dev.py down ``` - `init`: generates and preserves a private, ignored root `.env`; do not put its contents in Git, docs or chat. - `config`: validates Compose *when Docker is available*. - `up`: requests detached startup and readiness; **not yet validated on this host**. - `check`: probes `http://localhost:8080/debug/ready`. - `down`: stops Compose without deliberately deleting database/bootstrap volumes; never run `down -v` on data you need. - The local identity seed email/username is described in `core/backend/zitadel/README.md`, but actual initial sign-in has never been verified. - Self-signed/local HTTP is for local development only; no public network ports or production data. ## Account Portal OIDC client setup (NOT performed in P04) 1. Create a **dedicated confidential Web/OIDC app** in a disposable ZITADEL environment, using Authorization Code + PKCE. 2. Register the exact intended callback `http://localhost:3001/api/auth/callback/zitadel` for local development, or `https://account.vib.tools/api/auth/callback/zitadel` when production is explicitly deployed. Do not mix localhost callbacks into production. 3. Inject secure runtime-only settings from `users/ui/.env.example`: `ZITADEL_ISSUER`, `ZITADEL_CLIENT_ID`, `ZITADEL_CLIENT_SECRET`, `AUTH_SECRET`, `AUTH_URL`, `AUTH_TRUST_HOST`. 4. Keep confidential client secret and `AUTH_SECRET` server-side. Never use the backend master key, the official Login Client PAT or a browser-shared client secret as substitutes. 5. CI must create/approve a deterministic Account Portal dependency lockfile and check Auth.js beta/Next.js compatibility, then build/typecheck on an isolated runner. 6. Only after source/build acceptance, integrate Account Portal runtime, OIDC callbacks, HTTPS proxy headers and session behavior in a separately approved scope. 7. Confirm end-to-end login, expiry, logout semantics, API 401/200 response and account self-service permissions in disposable staging. **Production domains `auth.vib.tools` and `account.vib.tools` are design targets only.** Coolify configuration, TLS, persistent backup/restore, secure secret handling and production rollbacks are not implemented. ## User account / password / MFA management The Account Portal's profile page is currently **read-only**, and security page displays guidance/links. If ZITADEL self-service is enabled, users may be redirected to its built-in Console location; access is policy-dependent and not live-verified. Do not expect local Save Password, Enroll MFA, revoke device or account deletion buttons. ## Administrator boundaries ZITADEL Admin Console is distinct from the Account Portal. Never expose administrative API tokens or secrets to the browser. Identity administration should follow roles/policies, while billing/subscriptions/product permissions belong to individual SaaS applications. ## Gitea Actions verification (P05-CI-01) A manual-only workflow is defined in `.gitea/workflows/p05-ci.yml`. In Gitea go to `vibtools/ZitPlane` > Actions > **ZitPlane P05 CI Verification** > Run workflow (`main`). This runs on a registered Docker-capable `ubuntu-latest` runner, **not** your PC. See `docs/P05-CI-01.md` for its four gates and limitations. The CI workflow creates only disposable local test credentials and removes its own volumes; no real accounts, Coolify or production domains are accessed. ## Acceptance and configuration troubleshooting Refer to [FEATURES-STATUS.md](FEATURES-STATUS.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md), `docs/P02-EVIDENCE.md` and `docs/P04-ACCOUNT-PORTAL.md`. Do not claim success on a missing-run check. Future changes must update all affected docs and developer records.