feat: prepare isolated ZITADEL v4 local backend (Docker verification pending)
This commit is contained in:
1 parent
8f54ccb304
commit
433a0a32f8
9 files changed
+500
-68
No files matched your search
@@ -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
|
||||||
@@ -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.
|
|
||||||
@@ -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.
|
||||||
@@ -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())
|
||||||
@@ -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
@@ -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.
|
||||||
@@ -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
@@ -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.
|
||||||
@@ -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()
|
||||||
Reference in new issue
Block a user