# Developer quick guide ## Current status - P01 Foundation: committed. - P02 Local backend: configuration and helper implemented; **runtime verification blocked** because Docker is not installed on the connected Windows PC. - P03 Login V2: official v4.20.4 Next.js source and upstream pnpm/Nx/client/proto dependencies **imported** under `auth/ui/v2/`; builds/dependency installation and runtime verification **intentionally deferred to Gitea Actions**. - P04 Account Portal: independent Next.js/App Router + ZITADEL OIDC/Auth.js source and compact profile/security UI implemented under `users/ui/`; **no dependency install, lockfile, build, tests or runtime validation performed**. See `users/ui/README.md` and `docs/P04-ACCOUNT-PORTAL.md`. ## Getting local ZITADEL running 1. Install and launch Docker Desktop with Linux containers. Verify `docker compose version`. 2. Open PowerShell in `ZitPlane`. 3. Run `py core/backend/zitadel/dev.py init` once. This creates ignored local `.env` with random credentials; **never put secrets in Git**. 4. Run `py core/backend/zitadel/dev.py config` to validate Compose after Docker is installed. 5. Run `py core/backend/zitadel/dev.py up` to pull/start official images and verify `/debug/ready`. 6. Visit `http://localhost:8080/ui/console`. Log in as `zitadel-admin@zitadel.localhost` using the private generated initial password; change it as prompted. 7. Use `py core/backend/zitadel/dev.py down` to stop without destroying PostgreSQL or bootstrap-token volumes. The proxy is **loopback-only and HTTP-only**. It is for disposable local development, not shared network access or Coolify. Read `core/backend/zitadel/README.md` for expected persistence and limitations. ## Where to change code (future phases) - Official Go server: **no core source edits**, see `core/backend/zitadel/`. - Auth UI changes: `auth/ui/v2/apps/login/src/` (upstream workspace kept intact). See `auth/ui/v2/README.md` for beginner-friendly locations. - Account UI changes: `users/ui/src/app/`, `users/ui/src/components/`, and `users/ui/src/styles/`; protected identity/auth integration lives in `users/ui/src/auth.ts` and `users/ui/src/lib/` (no visual-only changes there). - Shared UI/components: `packages/` only if required by imported code. - Local Docker infrastructure: `deployment/docker/`. ## Development/production separation The P02 file `deployment/docker/compose.backend.dev.yaml` is not the production Compose file. Production secrets, HTTPS routing, remote domains, Admin access security, backup/restore and Coolify deployment are reserved for later approved phases. The dev master key and data **must never** be reused in production. ## Local checks ```powershell py -m unittest discover -s tests -p test_backend_dev.py -v git diff --check ``` A green stdlib-only test means only that local config and secret-generation contracts passed; it does **not** mean Docker images booted or authentication worked. ## P03 Login V2 — Source-only import The source lives at `auth/ui/v2/apps/login/` together with upstream `packages/zitadel-client`, `packages/zitadel-proto`, `proto` and the lockfile in `auth/ui/v2/`. **None of the following commands were run in P03.** A separately approved Gitea CI phase should run frozen install (reconcile the slim workspace lock if needed), proto generation, client and login builds, followed by isolated authentication checks. Do not replace the P02 prebuilt Login container without integration approval. Read `docs/P03-SOURCE-IMPORT.md` for upstream revision, exact source scope and pending acceptance gates. ## AI Studio and coding agents Allow AI to modify layout/components/styles only in approved UI scopes. Never replace ZITADEL session, OAuth, MFA or passkey logic with mocks. Do not use real credentials in screenshots/prompts. Run approved UI regression tests before integration.