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