Files
ZitPlane/docs/DEVELOPMENT.md
T

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. 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

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.