Files

40 lines
3.0 KiB
Markdown
Raw Permalink Normal View History

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