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 # 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 | | `core/backend/zitadel/` | Official ZITADEL backend integration and local helper |
| `auth/ui/v2/` | Customizable official Login V2 frontend, with required upstream build dependencies | | `deployment/docker/compose.backend.dev.yaml` | Loopback-only developer stack |
| `users/ui/` | Separate account management portal | | `auth/ui/v2/` | Future customized official Login V2 source (P03) |
| `packages/` | Shared UI and generated/API clients, only when actually needed | | `users/ui/` | Future account self-service portal (P04) |
| `deployment/` | Compose, reverse proxy, deployment configuration | | `packages/` | Shared packages only when needed |
| `scripts/` | Simple documented local developer entrypoints | | `tests/` | Focused contracts and future integration/UI tests |
| `tests/` | Focused integration and UI regression tests | | `docs/` | Architecture, scopes and developer instructions |
| `docs/` | Architecture, development guide, phase scopes |
## Planned domains ## Local development (requires Docker Desktop Linux containers)
- `auth.vib.tools` — ZITADEL OIDC/API, sign-in UI, built-in management console. ```powershell
- `account.vib.tools` — customer self-service account portal. 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. - `auth.vib.tools`: eventual ZITADEL API, official Console, customized login.
- ZITADEL stays upstream and version-pinned; no fork of its Go backend is planned. - `account.vib.tools`: future custom account portal.
- Dev/prod data and credentials stay separate. No secrets in Git. - Individual SaaS applications own their own billing, subscriptions and business databases.
- ZITADEL handles identity; individual SaaS products handle plans, billing and product data. - One Git repo, isolated containers; ZITADEL Go source remains upstream.
- One approved, scope-locked phase at a time. See [phases](docs/PHASES.md) and [agent rules](AGENTS.md).
## Start here ## 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.
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.
+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 # 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) ## Getting local ZITADEL running
- Login / signup / password recovery appearance: `auth/ui/v2/`. 1. Install and launch Docker Desktop with Linux containers. Verify `docker compose version`.
- Account dashboard appearance: `users/ui/`. 2. Open PowerShell in `ZitPlane`.
- Reusable color tokens and components: `packages/` (only after created). 3. Run `py core/backend/zitadel/dev.py init` once. This creates ignored local `.env` with random credentials; **never put secrets in Git**.
- ZITADEL image/config, not Go application code: `core/backend/zitadel/`. 4. Run `py core/backend/zitadel/dev.py config` to validate Compose after Docker is installed.
- Compose, HTTPS routing and service configuration: `deployment/`. 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 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.
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.
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 ## Development/production separation
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. 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 ## Local checks
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. ```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 # 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 ## P01 — Foundation (COMPLETE)
- **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/`. - Baseline commit `8f54ccb30426f2955472c0cd40fb94d0b18e86ac`.
- **Action:** Create compact repository structure; configure repository-local Git identity (Vib Tools / hello@vibtools.io); create initial local main-branch commit. - Initial monorepo folder structure, docs, project Git identity and clean commit completed.
- **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.
## P02 — ZITADEL local backend (proposed; NOT approved) ## P02 — ZITADEL local backend (APPROVED 2026-11-22)
- **Write scope to approve:** `core/backend/zitadel/**`, `deployment/docker/compose.backend.dev.yaml`, `.env.example`, backend-focused `tests/**`, and narrowly `docs/**` / `README.md`. - **Allowed source writes:** `core/backend/zitadel/**`, `deployment/docker/compose.backend.dev.yaml`, `.env.example`, backend-focused `tests/**`, and narrow `docs/**` / `README.md`.
- Pin official image version/digest, local PostgreSQL and persistence, safe bootstrap + local test admin, startup/health checks. No Go backend vendoring. - Official versioned ZITADEL v4 backend image, local PostgreSQL persistence, secure random dev secret generation, first-admin bootstrap and health checks.
- No public domain, Coolify deploy, real users, Login V2 import, new UI or production master keys. - Official prebuilt Login V2 image as a **runtime dependency only** (v4 Admin Console login requires it); no Login V2 source import.
- Focused acceptance: local startup + admin console reachability, persistence after restart, and clean shutdown; document exact lock and versions. - 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) ## P03 — Login V2 import (proposed, NOT approved)
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. 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) ## P04 — Account portal foundation (proposed, NOT approved)
Implement OIDC-protected basic user self-service skeleton under `users/ui/`; no fake production authentication. OIDC-protected basic account self-service skeleton; no fake production authentication.
## P05 — Integration (proposed) ## P05 — Integration (proposed, NOT approved)
Local development workflows, shared design tokens as needed, production-safe Compose topology, routing drafts, tests and docs. No live deployment. Local development, shared UI tokens as needed, production-safe Docker topology, routing drafts, tests/docs. No live deployment.
## P06 — UI redesign (proposed) ## P06 — UI redesign (proposed, NOT approved)
Compact login and account UI, accessibility, responsive design and scoped visual regression. No change to protected authentication semantics. Compact login and account UI, accessibility, responsive design and scoped regressions. Protected authentication semantics unchanged.
## P07 — Production deployment (proposed) ## P07 — Production deployment (proposed, NOT approved)
Coolify, secured external domains, HTTPS, secrets, backups, persistent volumes and focused end-to-end readiness checks; only on explicit approval. 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()