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)
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:8080only (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(especiallyZITADEL_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.