Files
ZitPlane/docs/DEVELOPMENT.md
T

2.5 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.
  • No customized Login V2 or Account Portal source has been imported yet.

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/ after P03 import.
  • Account UI changes: users/ui/ after P04.
  • 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.

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.