3.8 KiB
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. Seeusers/ui/README.mdanddocs/P04-ACCOUNT-PORTAL.md.
Getting local ZITADEL running
- Install and launch Docker Desktop with Linux containers. Verify
docker compose version. - Open PowerShell in
ZitPlane. - Run
py core/backend/zitadel/dev.py initonce. This creates ignored local.envwith random credentials; never put secrets in Git. - Run
py core/backend/zitadel/dev.py configto validate Compose after Docker is installed. - Run
py core/backend/zitadel/dev.py upto pull/start official images and verify/debug/ready. - Visit
http://localhost:8080/ui/console. Log in aszitadel-admin@zitadel.localhostusing the private generated initial password; change it as prompted. - Use
py core/backend/zitadel/dev.py downto 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). Seeauth/ui/v2/README.mdfor beginner-friendly locations. - Account UI changes:
users/ui/src/app/,users/ui/src/components/, andusers/ui/src/styles/; protected identity/auth integration lives inusers/ui/src/auth.tsandusers/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
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.