feat: prepare isolated ZITADEL v4 local backend (Docker verification pending)

This commit is contained in:
Vib Tools committed 2026-11-22 04:02:48 -08:00
1 parent 8f54ccb304
commit 433a0a32f8
9 files changed
+500 -68

No files matched your search

+7
View File
@@ -0,0 +1,7 @@
# ZitPlane P02 LOCAL DEV ONLY: informative template; not real credentials.
# Generate a private, ignored .env using: py core/backend/zitadel/dev.py init
# Do NOT use placeholders below as credentials.
POSTGRES_PASSWORD=GENERATE_LOCALLY
ZITADEL_MASTERKEY=GENERATE_EXACTLY_32_CHARACTERS
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD=GENERATE_LOCALLY
LOGIN_SESSION_COOKIE_SECRET=GENERATE_LOCALLY
+29 -27
View File
@@ -1,39 +1,41 @@
# ZitPlane
A compact, developer-friendly monorepo for central identity, branded sign-in, and account self-service.
Compact, developer-friendly monorepo for a central identity service, a branded login frontend and an independent user self-service account portal.
**Status:** Phase 01 — repository foundation only. No backend, login app, account portal, or Docker stack has been installed yet.
## Current phase status
- **P01 Foundation:** complete, initial commit `8f54ccb`.
- **P02 ZITADEL local backend:** pinned official images, development Compose, secure local bootstrap helper and focused static tests implemented. **Docker startup and Admin Console integration remain unverified** because the connected Windows PC has no Docker CLI.
- **P03 Login V2 source / P04 Account Portal:** not started.
- **Production / Coolify:** not configured or deployed.
## Planned components
## Responsibility map
| Path | Responsibility |
| Path | Purpose |
| --- | --- |
| `core/backend/zitadel/` | Version-pinned official ZITADEL backend configuration; **not** a copy of its Go source |
| `auth/ui/v2/` | Customizable official Login V2 frontend, with required upstream build dependencies |
| `users/ui/` | Separate account management portal |
| `packages/` | Shared UI and generated/API clients, only when actually needed |
| `deployment/` | Compose, reverse proxy, deployment configuration |
| `scripts/` | Simple documented local developer entrypoints |
| `tests/` | Focused integration and UI regression tests |
| `docs/` | Architecture, development guide, phase scopes |
| `core/backend/zitadel/` | Official ZITADEL backend integration and local helper |
| `deployment/docker/compose.backend.dev.yaml` | Loopback-only developer stack |
| `auth/ui/v2/` | Future customized official Login V2 source (P03) |
| `users/ui/` | Future account self-service portal (P04) |
| `packages/` | Shared packages only when needed |
| `tests/` | Focused contracts and future integration/UI tests |
| `docs/` | Architecture, scopes and developer instructions |
## Planned domains
## Local development (requires Docker Desktop Linux containers)
- `auth.vib.tools` — ZITADEL OIDC/API, sign-in UI, built-in management console.
- `account.vib.tools` — customer self-service account portal.
```powershell
py core/backend/zitadel/dev.py init
py core/backend/zitadel/dev.py config
py core/backend/zitadel/dev.py up
```
These domains are design targets; they are **not deployed or configured yet**.
When the backend stack is actually running, the local Admin Console is expected at `http://localhost:8080/ui/console`. This is **not** a currently verified working URL. See [backend setup](core/backend/zitadel/README.md) and [developer guide](docs/DEVELOPMENT.md).
## Ground rules
## Intended public architecture (not deployed)
- One Git repository, multiple isolated Docker services at runtime.
- ZITADEL stays upstream and version-pinned; no fork of its Go backend is planned.
- Dev/prod data and credentials stay separate. No secrets in Git.
- ZITADEL handles identity; individual SaaS products handle plans, billing and product data.
- One approved, scope-locked phase at a time. See [phases](docs/PHASES.md) and [agent rules](AGENTS.md).
- `auth.vib.tools`: eventual ZITADEL API, official Console, customized login.
- `account.vib.tools`: future custom account portal.
- Individual SaaS applications own their own billing, subscriptions and business databases.
- One Git repo, isolated containers; ZITADEL Go source remains upstream.
## Start here
1. Read [architecture](docs/ARCHITECTURE.md) and [development](docs/DEVELOPMENT.md).
2. Approve Phase 02 before adding ZITADEL or any Docker startup configuration.
3. Do not run an application from this foundation-only scaffold; none has been installed.
## Working agreements
Read [AGENTS.md](AGENTS.md), [architecture](docs/ARCHITECTURE.md) and [phase scopes](docs/PHASES.md). Use separate, expressly approved phases; no production secrets or user data in Git.
+39 -2
View File
@@ -1,3 +1,40 @@
# ZITADEL backend integration
# ZitPlane — ZITADEL local backend (P02)
Reserved for version-pinned **official ZITADEL image** configuration and setup instructions in Phase 02. No Go source vendoring or image download in Phase 01.
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.
+145
View File
@@ -0,0 +1,145 @@
"""Local-only ZitPlane backend helper (Python stdlib, no dependencies).
Run from any folder:
py core/backend/zitadel/dev.py init
py core/backend/zitadel/dev.py up
py core/backend/zitadel/dev.py check
py core/backend/zitadel/dev.py down
No credentials are printed, committed or transmitted by this script.
"""
from __future__ import annotations
import argparse
import os
from pathlib import Path
import secrets
import shutil
import string
import subprocess
import sys
import urllib.error
import urllib.request
ROOT = Path(__file__).resolve().parents[3]
COMPOSE = ROOT / "deployment" / "docker" / "compose.backend.dev.yaml"
ENV = ROOT / ".env"
VARIABLES = (
"POSTGRES_PASSWORD",
"ZITADEL_MASTERKEY",
"ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD",
"LOGIN_SESSION_COOKIE_SECRET",
)
def random_chars(alphabet: str, length: int) -> str:
return "".join(secrets.choice(alphabet) for _ in range(length))
def create_dev_env() -> bool:
"""Generate local secrets once and never overwrite an existing .env."""
if ENV.exists():
print("Existing .env preserved (credentials were not regenerated).")
return False
alphabet = string.ascii_letters + string.digits
values = {
"POSTGRES_PASSWORD": random_chars(alphabet, 48),
"ZITADEL_MASTERKEY": random_chars(alphabet, 32),
"ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD": (
"Zp!7" + random_chars(alphabet, 29)
),
"LOGIN_SESSION_COOKIE_SECRET": random_chars(alphabet, 48),
}
lines = [
"# Local ZitPlane development only. NEVER COMMIT or deploy to Coolify.",
"# The first admin is zitadel-admin@zitadel.localhost.",
"# Keep this file: rotating the ZITADEL master key will break existing encrypted data.",
]
lines.extend(f"{key}={value}" for key, value in values.items())
try:
with ENV.open("x", encoding="utf-8", newline="\n") as fh:
fh.write("\n".join(lines) + "\n")
except FileExistsError:
print("Existing .env preserved (race-safe).")
return False
if os.name != "nt":
os.chmod(ENV, 0o600)
print("Created ignored .env with random development credentials; values hidden.")
return True
def validate_env() -> None:
if not ENV.is_file():
raise RuntimeError("Missing .env. Run: py core/backend/zitadel/dev.py init")
data: dict[str, str] = {}
for line in ENV.read_text(encoding="utf-8").splitlines():
if not line.strip() or line.lstrip().startswith("#"):
continue
if "=" not in line:
raise RuntimeError("Invalid .env entry.")
key, value = line.split("=", 1)
data[key] = value
if any(not data.get(key) for key in VARIABLES):
raise RuntimeError("Local .env is missing one or more required variables.")
if len(data["ZITADEL_MASTERKEY"]) != 32:
raise RuntimeError("ZITADEL_MASTERKEY must be exactly 32 characters.")
if len(data["LOGIN_SESSION_COOKIE_SECRET"]) < 32:
raise RuntimeError("LOGIN_SESSION_COOKIE_SECRET must be >= 32 characters.")
if len(data["ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD"]) < 16:
raise RuntimeError("Admin password too short.")
def docker_compose(*args: str) -> None:
if not shutil.which("docker"):
raise RuntimeError(
"Docker CLI is not installed or not on PATH. Install/start Docker Desktop "
"with Linux containers; no Docker installation is performed automatically."
)
command = ["docker", "compose", "--env-file", str(ENV), "-f", str(COMPOSE), *args]
completed = subprocess.run(command, cwd=ROOT, check=False)
if completed.returncode:
raise RuntimeError(f"Docker Compose exited with code {completed.returncode}.")
def check_ready() -> None:
url = "http://localhost:8080/debug/ready"
try:
with urllib.request.urlopen(url, timeout=8) as response:
if response.status != 200:
raise RuntimeError(f"Readiness HTTP status: {response.status}")
print(f"PASS: ZITADEL ready at {url}")
print("Admin console: http://localhost:8080/ui/console")
except (urllib.error.URLError, TimeoutError) as exc:
raise RuntimeError(f"ZITADEL not ready at {url}: {exc}") from exc
def main() -> int:
parser = argparse.ArgumentParser(description="ZitPlane local-only ZITADEL backend")
parser.add_argument("action", choices=["init", "up", "check", "down", "ps", "config"])
args = parser.parse_args()
try:
if args.action == "init":
create_dev_env()
validate_env()
return 0
if args.action == "check":
check_ready()
return 0
validate_env()
if args.action == "up":
docker_compose("up", "-d", "--wait")
check_ready()
elif args.action == "down":
docker_compose("down") # never remove volumes
elif args.action == "ps":
docker_compose("ps")
elif args.action == "config":
docker_compose("config", "--quiet")
except RuntimeError as exc:
print(f"BLOCKED: {exc}", file=sys.stderr)
return 1
return 0
if __name__ == "__main__":
raise SystemExit(main())
+144
View File
@@ -0,0 +1,144 @@
# ZitPlane P02: development-only ZITADEL v4 stack.
# Run from the repository root: python core/backend/zitadel/dev.py up
# Do NOT deploy this Compose file to Coolify or expose its HTTP port publicly.
name: zitplane-backend-dev
services:
postgres:
image: postgres:17.10-alpine
restart: unless-stopped
environment:
POSTGRES_DB: zitadel
POSTGRES_USER: zitadel
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Run dev.py init first}
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U zitadel -d zitadel"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
networks: [internal]
zitadel-api:
image: ghcr.io/zitadel/zitadel:v4.20.4
restart: unless-stopped
user: "0" # matches official bootstrap volume-writer requirement in local dev
command: ["start-from-init", "--masterkey", "${ZITADEL_MASTERKEY:?Run dev.py init first}"]
environment:
ZITADEL_PORT: "8080"
ZITADEL_EXTERNALDOMAIN: localhost
ZITADEL_EXTERNALPORT: "8080"
ZITADEL_EXTERNALSECURE: "false"
ZITADEL_TLS_ENABLED: "false"
ZITADEL_DATABASE_POSTGRES_DSN: "postgresql://zitadel:${POSTGRES_PASSWORD:?Run dev.py init first}@postgres:5432/zitadel?sslmode=disable"
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: zitadel-admin
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL: zitadel-admin@zitadel.localhost
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_VERIFIED: "true"
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: ${ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD:?Run dev.py init first}
ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"
ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH: /zitadel/bootstrap/login-client.pat
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME: login-client
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: ZitPlane_Local_Login_Client
ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE: "2028-01-01T00:00:00Z"
ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: "true"
ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI: "http://localhost:8080/ui/v2/login/"
ZITADEL_OIDC_DEFAULTLOGINURLV2: "http://localhost:8080/ui/v2/login/login?authRequest="
ZITADEL_OIDC_DEFAULTLOGOUTURLV2: "http://localhost:8080/ui/v2/login/logout?post_logout_redirect="
ZITADEL_SAML_DEFAULTLOGINURLV2: "http://localhost:8080/ui/v2/login/login?samlRequest="
volumes:
- zitadel-bootstrap:/zitadel/bootstrap
depends_on:
postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "/app/zitadel", "ready"]
interval: 10s
timeout: 30s
retries: 12
start_period: 20s
networks: [internal]
labels:
- traefik.enable=true
- traefik.http.services.zitadel-api.loadbalancer.server.port=8080
- traefik.http.services.zitadel-api.loadbalancer.server.scheme=h2c
- traefik.http.routers.zitadel-api.rule=Host(`localhost`) && !PathPrefix(`/ui/v2/login`) && !PathPrefix(`/api`) && !Path(`/`)
- traefik.http.routers.zitadel-api.entrypoints=web
- traefik.http.routers.zitadel-api.service=zitadel-api
- traefik.http.routers.zitadel-api.priority=100
- traefik.http.middlewares.zitadel-strip-api.stripprefix.prefixes=/api
- traefik.http.routers.zitadel-api-alias.rule=Host(`localhost`) && PathPrefix(`/api`)
- traefik.http.routers.zitadel-api-alias.entrypoints=web
- traefik.http.routers.zitadel-api-alias.middlewares=zitadel-strip-api
- traefik.http.routers.zitadel-api-alias.service=zitadel-api
- traefik.http.routers.zitadel-api-alias.priority=200
zitadel-login:
# Temporary official, unmodified image to make the v4 Admin Console usable.
# Phase 03 will import matching Login V2 source; no UI source is imported here.
image: ghcr.io/zitadel/zitadel-login:v4.20.4
restart: unless-stopped
user: "0" # official image parity for mounted bootstrap-token access
environment:
ZITADEL_API_URL: http://zitadel-api:8080
NEXT_PUBLIC_BASE_PATH: /ui/v2/login
ZITADEL_SERVICE_USER_TOKEN_FILE: /zitadel/bootstrap/login-client.pat
ZITADEL_SESSION_COOKIE_SECRET: ${LOGIN_SESSION_COOKIE_SECRET:?Run dev.py init first}
CUSTOM_REQUEST_HEADERS: "Host:localhost,X-Forwarded-Proto:http"
volumes:
- zitadel-bootstrap:/zitadel/bootstrap:ro
depends_on:
zitadel-api:
condition: service_healthy
healthcheck:
test: ["CMD", "/bin/sh", "-c", "node /app/healthcheck.mjs http://localhost:3000/ui/v2/login/healthy"]
interval: 10s
timeout: 30s
retries: 12
start_period: 20s
networks: [internal]
labels:
- traefik.enable=true
- traefik.http.services.zitadel-login.loadbalancer.server.port=3000
- traefik.http.middlewares.zitadel-root-rewrite.replacepath.path=/ui/v2/login/
- traefik.http.routers.zitadel-root.rule=Host(`localhost`) && Path(`/`)
- traefik.http.routers.zitadel-root.entrypoints=web
- traefik.http.routers.zitadel-root.middlewares=zitadel-root-rewrite
- traefik.http.routers.zitadel-root.service=zitadel-login
- traefik.http.routers.zitadel-root.priority=400
- traefik.http.routers.zitadel-login.rule=Host(`localhost`) && PathPrefix(`/ui/v2/login`)
- traefik.http.routers.zitadel-login.entrypoints=web
- traefik.http.routers.zitadel-login.service=zitadel-login
- traefik.http.routers.zitadel-login.priority=250
proxy:
image: traefik:v3.7.7
restart: unless-stopped
command:
- --providers.docker=true
- --providers.docker.exposedbydefault=false
- --providers.docker.network=zitplane-backend-dev-internal
- --entrypoints.web.address=:80
- --api.dashboard=false
- --api.insecure=false
- --ping=true
- --log.level=WARN
ports:
- "127.0.0.1:8080:80"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
depends_on:
zitadel-api:
condition: service_healthy
zitadel-login:
condition: service_healthy
networks: [internal]
networks:
internal:
name: zitplane-backend-dev-internal
volumes:
postgres-data:
zitadel-bootstrap:
+30 -18
View File
@@ -1,25 +1,37 @@
# Developer quick guide
**Current phase:** Foundation only. No `npm install`, Docker build or login preview is available yet.
## 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.
## Where to make changes (after later phases)
- Login / signup / password recovery appearance: `auth/ui/v2/`.
- Account dashboard appearance: `users/ui/`.
- Reusable color tokens and components: `packages/` (only after created).
- ZITADEL image/config, not Go application code: `core/backend/zitadel/`.
- Compose, HTTPS routing and service configuration: `deployment/`.
## Getting local ZITADEL running
1. Install and launch Docker Desktop with Linux containers. Verify `docker compose version`.
2. Open PowerShell in `ZitPlane`.
3. Run `py core/backend/zitadel/dev.py init` once. This creates ignored local `.env` with random credentials; **never put secrets in Git**.
4. Run `py core/backend/zitadel/dev.py config` to validate Compose after Docker is installed.
5. Run `py core/backend/zitadel/dev.py up` to pull/start official images and verify `/debug/ready`.
6. Visit `http://localhost:8080/ui/console`. Log in as `zitadel-admin@zitadel.localhost` using the private generated initial password; change it as prompted.
7. Use `py core/backend/zitadel/dev.py down` to stop without destroying PostgreSQL or bootstrap-token volumes.
## Planned local development
1. Install Git, Node.js with compatible pnpm and Docker Desktop.
2. Start a **local-only** ZITADEL + PostgreSQL stack using a later phase's documented script.
3. Start Login V2 and Account UI in Next.js development mode (hot reload).
4. Use test accounts, synthetic profile data and local-only UI states.
5. Inspect mobile/desktop, keyboard accessibility and full auth flows before any production build.
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.
Commands, required versions and ports will be documented when the real upstream dependencies are installed. Do not guess them from this scaffold.
## 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/`.
## Working with AI Studio / coding agents
Ask for changes scoped to JSX/TSX, CSS and design tokens. Review the resulting diff before integrating. Never paste generated mock auth, fake JWT handlers or browser-side admin API credentials into production. Protected auth/route code requires separate approval and focused security testing.
## 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.
## Deployment rule
Coolify must use an explicit, production-safe Compose configuration. Local overrides and secrets must not be copied into production. Production deploy is not part of Phase 01.
## Local checks
```powershell
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.
+32
View File
@@ -0,0 +1,32 @@
# P02 — Local backend integration evidence
Date: 2026-11-22
Baseline: `8f54ccb30426f2955472c0cd40fb94d0b18e86ac`
Scope: `docs/PHASES.md` P02.
## What was introduced
- Official ZITADEL v4.20.4 Go image; matching official prebuilt Login V2 v4.20.4 runtime dependency.
- PostgreSQL 17.10 Alpine, Traefik 3.7.7; Docker Compose loopback-only development stack.
- Generated random, local-only ignored `.env` with non-overwriting setup; no secrets committed.
- Backend health check via `/app/zitadel ready`, HTTP probe via `/debug/ready`.
- Persistent Postgres and login client token volumes; no port exposure besides local 127.0.0.1:8080.
- Local helper commands and focused unittest contracts.
## Verification status
- Baseline hash and existing unrelated untracked file: inspected before changes.
- PC Python: 3.12.0; Docker CLI/Desktop: not detected; PyYAML: not installed.
- Python stdlib focused tests: **3/3 PASS**, 0 failures (secret generation/idempotence; version-pinned local-only Compose contract; secrets ignored).
- Dev `.env`: generated locally with random secrets, values not printed; `git check-ignore .env` = PASS.
- Exact staged patch: 9 approved files; `git diff --cached --check` = PASS; unrelated `AI_INSTRUCTIONS.md` left untracked and unchanged.
- Docker Compose validation via `docker compose config`: **BLOCKED** (Docker missing).
- Actual backend image pull/start: **BLOCKED** (Docker missing).
- Admin Console login: **NOT TESTED**.
- Database persistence across restart: **NOT TESTED**.
- Safe shutdown/no volume removal: only script behavior reviewed; **runtime NOT TESTED**.
## Exit criteria / unresolved item
This phase can be committed as a **configuration-ready, runtime-unverified** checkpoint, but must not be marked full backend acceptance. Once Docker Desktop with Linux containers is installed, run the documented local init/config/up/ps/check/down workflow, verify Admin Console and persistence, and record results in a separately approved follow-up scope. No production deployment is permitted from this developer Compose.
## Safety notes
- The new dev Compose stack uses local HTTP and password pre-verification for a synthetic local administrator; do not deploy as production.
- P02 does not include UI source, Coolify deployment, domain changes or external Git actions.
+22 -21
View File
@@ -1,30 +1,31 @@
# Phase register and scope locks
Only **Phase 01** is approved for implementation in this session. Each later phase requires its own explicit approval and exact scope lock.
Implement one explicitly approved phase at a time. Keep out-of-scope files, existing authentication machinery and production systems unchanged.
## P01 — Foundation
- **Allowed writes:** `README.md`, `AGENTS.md`, `.gitignore`, `.editorconfig`, `docs/**`, and README placeholders under `core/backend/zitadel/`, `auth/ui/v2/`, `users/ui/`, `packages/`, `deployment/`, `scripts/`, `tests/`.
- **Action:** Create compact repository structure; configure repository-local Git identity (Vib Tools / hello@vibtools.io); create initial local main-branch commit.
- **Excluded:** Backend source/image download, dependencies, UI code, Compose deployment, secrets, external Git pushes, builds.
- **Acceptance:** Repository tree and Git identity confirmed; no unexpected files; clean worktree after commit.
## P01 — Foundation (COMPLETE)
- Baseline commit `8f54ccb30426f2955472c0cd40fb94d0b18e86ac`.
- Initial monorepo folder structure, docs, project Git identity and clean commit completed.
## P02 — ZITADEL local backend (proposed; NOT approved)
- **Write scope to approve:** `core/backend/zitadel/**`, `deployment/docker/compose.backend.dev.yaml`, `.env.example`, backend-focused `tests/**`, and narrowly `docs/**` / `README.md`.
- Pin official image version/digest, local PostgreSQL and persistence, safe bootstrap + local test admin, startup/health checks. No Go backend vendoring.
- No public domain, Coolify deploy, real users, Login V2 import, new UI or production master keys.
- Focused acceptance: local startup + admin console reachability, persistence after restart, and clean shutdown; document exact lock and versions.
## P02 — ZITADEL local backend (APPROVED 2026-11-22)
- **Allowed source writes:** `core/backend/zitadel/**`, `deployment/docker/compose.backend.dev.yaml`, `.env.example`, backend-focused `tests/**`, and narrow `docs/**` / `README.md`.
- Official versioned ZITADEL v4 backend image, local PostgreSQL persistence, secure random dev secret generation, first-admin bootstrap and health checks.
- Official prebuilt Login V2 image as a **runtime dependency only** (v4 Admin Console login requires it); no Login V2 source import.
- No backend Go source vendoring, UI redesign, public domain, Coolify deploy, production keys, remote push or changes to unrelated files.
- Verify: static focused test/patch audit; with Docker available, live startup/ready/Admin Console, persistent DB after restart and shutdown.
- **Execution evidence:** Docker CLI/Desktop absent on connected Windows PC; live Compose startup, admin login and persistence remain BLOCKED, not passed. Local static verification results and Git commit are recorded upon phase closure in `docs/P02-EVIDENCE.md`.
- Existing unrelated untracked `AI_INSTRUCTIONS.md` must remain untouched.
## P03 — Login V2 import (proposed)
Import one compatible official upstream commit including required workspace/dependencies under approved paths; unmodified functional baseline; verify one build and baseline auth route. No visual redesign.
## P03 — Login V2 import (proposed, NOT approved)
Import one compatible upstream commit and necessary workspace/dependencies under an exact approved scope; verify original behavior. No visual redesign. Do not claim P02 runtime integration was verified if Docker remains unavailable.
## P04 — Account portal foundation (proposed)
Implement OIDC-protected basic user self-service skeleton under `users/ui/`; no fake production authentication.
## P04 — Account portal foundation (proposed, NOT approved)
OIDC-protected basic account self-service skeleton; no fake production authentication.
## P05 — Integration (proposed)
Local development workflows, shared design tokens as needed, production-safe Compose topology, routing drafts, tests and docs. No live deployment.
## P05 — Integration (proposed, NOT approved)
Local development, shared UI tokens as needed, production-safe Docker topology, routing drafts, tests/docs. No live deployment.
## P06 — UI redesign (proposed)
Compact login and account UI, accessibility, responsive design and scoped visual regression. No change to protected authentication semantics.
## P06 — UI redesign (proposed, NOT approved)
Compact login and account UI, accessibility, responsive design and scoped regressions. Protected authentication semantics unchanged.
## P07 — Production deployment (proposed)
Coolify, secured external domains, HTTPS, secrets, backups, persistent volumes and focused end-to-end readiness checks; only on explicit approval.
## P07 — Production deployment (proposed, NOT approved)
Coolify, HTTPS, secrets, backups, durable storage and focused production readiness; explicit approval required.
+52
View File
@@ -0,0 +1,52 @@
"""Focused, stdlib-only P02 local backend config checks (no Docker required)."""
import importlib.util
from pathlib import Path
import re
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
MODULE_PATH = ROOT / "core" / "backend" / "zitadel" / "dev.py"
SPEC = importlib.util.spec_from_file_location("zitplane_dev", MODULE_PATH)
assert SPEC and SPEC.loader
dev = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(dev)
class BackendDevContract(unittest.TestCase):
def test_initialization_is_private_and_idempotent(self):
with tempfile.TemporaryDirectory() as directory:
old_env = dev.ENV
dev.ENV = Path(directory) / ".env"
try:
self.assertTrue(dev.create_dev_env())
dev.validate_env()
data = dev.ENV.read_text(encoding="utf-8")
self.assertEqual(len(re.search(r"^ZITADEL_MASTERKEY=(.+)$", data, re.M).group(1)), 32)
self.assertFalse(dev.create_dev_env())
self.assertEqual(data, dev.ENV.read_text(encoding="utf-8"))
finally:
dev.ENV = old_env
def test_compose_local_only_and_version_pinned(self):
data = dev.COMPOSE.read_text(encoding="utf-8")
self.assertIn("ghcr.io/zitadel/zitadel:v4.20.4", data)
self.assertIn("ghcr.io/zitadel/zitadel-login:v4.20.4", data)
self.assertIn("postgres:17.10-alpine", data)
self.assertIn("127.0.0.1:8080:80", data)
self.assertNotIn("0.0.0.0:8080", data)
self.assertNotIn("POSTGRES_PASSWORD: postgres", data)
self.assertIn("postgres-data:/var/lib/postgresql/data", data)
self.assertIn("zitadel-bootstrap:/zitadel/bootstrap", data)
self.assertIn("condition: service_healthy", data)
self.assertIn("PathPrefix", data)
self.assertIn("server.scheme=h2c", data)
def test_secrets_ignored(self):
ignore = (ROOT / ".gitignore").read_text(encoding="utf-8")
self.assertIn("\n.env\n", "\n" + ignore)
self.assertNotIn("MasterkeyNeedsToHave32Characters", dev.COMPOSE.read_text(encoding="utf-8"))
if __name__ == "__main__":
unittest.main()