From 433a0a32f8c4ad0a8ab3b36f6c6fcd8671c0bb18 Mon Sep 17 00:00:00 2001 From: Vib Tools Date: Sun, 22 Nov 2026 04:02:48 -0800 Subject: [PATCH] feat: prepare isolated ZITADEL v4 local backend (Docker verification pending) --- .env.example | 7 + README.md | 56 ++++---- core/backend/zitadel/README.md | 41 +++++- core/backend/zitadel/dev.py | 145 +++++++++++++++++++++ deployment/docker/compose.backend.dev.yaml | 144 ++++++++++++++++++++ docs/DEVELOPMENT.md | 48 ++++--- docs/P02-EVIDENCE.md | 32 +++++ docs/PHASES.md | 43 +++--- tests/test_backend_dev.py | 52 ++++++++ 9 files changed, 500 insertions(+), 68 deletions(-) create mode 100644 .env.example create mode 100644 core/backend/zitadel/dev.py create mode 100644 deployment/docker/compose.backend.dev.yaml create mode 100644 docs/P02-EVIDENCE.md create mode 100644 tests/test_backend_dev.py diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..79facdc --- /dev/null +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index 33f8661..c49fdc4 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/core/backend/zitadel/README.md b/core/backend/zitadel/README.md index 7e355aa..e2c0e32 100644 --- a/core/backend/zitadel/README.md +++ b/core/backend/zitadel/README.md @@ -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. diff --git a/core/backend/zitadel/dev.py b/core/backend/zitadel/dev.py new file mode 100644 index 0000000..de3fac3 --- /dev/null +++ b/core/backend/zitadel/dev.py @@ -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()) diff --git a/deployment/docker/compose.backend.dev.yaml b/deployment/docker/compose.backend.dev.yaml new file mode 100644 index 0000000..27da054 --- /dev/null +++ b/deployment/docker/compose.backend.dev.yaml @@ -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: diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index f86df43..af8c037 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -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. diff --git a/docs/P02-EVIDENCE.md b/docs/P02-EVIDENCE.md new file mode 100644 index 0000000..371a68c --- /dev/null +++ b/docs/P02-EVIDENCE.md @@ -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. diff --git a/docs/PHASES.md b/docs/PHASES.md index a7843db..94f90b1 100644 --- a/docs/PHASES.md +++ b/docs/PHASES.md @@ -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. diff --git a/tests/test_backend_dev.py b/tests/test_backend_dev.py new file mode 100644 index 0000000..52466bb --- /dev/null +++ b/tests/test_backend_dev.py @@ -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()