41 lines
3.0 KiB
Markdown
41 lines
3.0 KiB
Markdown
# 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.
|