# ZitPlane — ZITADEL local backend (P02) The **official ZITADEL Go backend is not vendored** here. The dev stack pins: - `ghcr.io/zitadel/zitadel:v4.20.4` (backend) - `ghcr.io/zitadel/zitadel-login:v4.20.4` (temporary, unmodified UI dependency for usable Admin Console) - `postgres:17.10-alpine`, `traefik:v3.7.7` (development infrastructure) Upstream references: - https://zitadel.com/docs/self-hosting/deploy/compose - https://github.com/zitadel/zitadel/blob/v4.20.4/deploy/compose/docker-compose.yml - https://zitadel.com/docs/apis/observability/health ## Prerequisites - Docker Desktop **Linux containers** with `docker compose` (not installed automatically). - Python 3.10+ (stdlib only), local loopback port 8080 available. - Do not start this dev Compose stack on a public server. ## Local commands (from repository root) ```powershell py core/backend/zitadel/dev.py init py core/backend/zitadel/dev.py config py core/backend/zitadel/dev.py up py core/backend/zitadel/dev.py check py core/backend/zitadel/dev.py ps py core/backend/zitadel/dev.py down ``` `init` generates four random secrets into ignored root `.env` (never prints values). It is idempotent and never overwrites an existing .env. `down` stops services **without deleting persistent volumes**. Do not run `docker compose down -v` on a database you need. Once running, use **http://localhost:8080/ui/console** with username `zitadel-admin@zitadel.localhost` and the bootstrap admin password found locally in `.env` (never share it). A password change is required. For the first admin setup, local email verification is pre-verified; **never use this development shortcut for production users**. The initial admin password and most `FIRSTINSTANCE_` settings only apply the first time a database is initialized. No SMTP is configured; password-recovery emails won't work locally until a later, separately approved integration. ## Boundaries - HTTP is bound to `127.0.0.1:8080` only (no LAN/public exposure). PostgreSQL and API/login ports are internal-only. - The official Login V2 **container** is a runtime dependency, **not the customized Login V2 source import**. Phase 03 will replace/import at its separately approved scope. - The shared bootstrap PAT and database survive restarts via Docker named volumes. Its configured initial expiration is 2028-01-01; renewal/rotation needs planning before then. - Avoid deleting `.env` (especially `ZITADEL_MASTERKEY`) while retaining volumes, because the master key protects encrypted data. - When ready for production, design a **separate** hardened stack with HTTPS, durable secrets, backups and role-restricted database access. This Compose file must never be used as-is in Coolify. ## Initial machine audit (2026-11-22) The connected Windows host has Python 3.12, but no Docker CLI/Docker Desktop was detected. Runtime startup, real readiness, Admin Console login and volume persistence **cannot be certified on this host** until Docker is installed and running. Static tests cannot substitute for live integration tests.