Files
ZitPlane/docs/SETUP-GUIDE.md
T

16 KiB

ZitPlane — Development & Deployment Setup Guide

State: This is a guide to the current source and planned integration gates, not proof a live install is available. No public Coolify deployment or Gitea Actions CI exists at P04.

System pieces

  • Official Go ZITADEL backend v4.20.4 (Docker image), PostgreSQL 17.10 and Traefik 3.7.7 configured in deployment/docker/compose.backend.dev.yaml.
  • Prebuilt official ZITADEL Login V2 image for that local-only Compose.
  • Imported, unchanged official Login V2 Next.js source under auth/ui/v2/ (not wired to Compose).
  • Next.js Account Portal source under users/ui/ (not started or wired to Compose).

Requirements for optional local development (future; do not use production user data)

  • Windows/macOS/Linux host with a supported Docker engine + Docker Compose (Docker Desktop with Linux containers on Windows).
  • Git, Python 3.10+ for P02 dev.py.
  • Account Portal requires Node.js meeting users/ui/package.json engine constraint (Node 22+) and dependencies after a reviewed lockfile is created.
  • Login V2 requires its own upstream Node/pnpm/Nx toolchain; exact frozen-install compatibility has not been established.
  • Local loopback TCP 8080 for the development ZITADEL proxy. Account Portal intended local port 3001 after a dev integration step.

P02 local-only bootstrap commands

The core/backend/zitadel/README.md is the authoritative current helper guide. The following commands are instructions only (not executed in this documentation task):

cd C:\Users\Administrator\Desktop\Projects\ZitPlane
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 and preserves a private, ignored root .env; do not put its contents in Git, docs or chat.
  • config: validates Compose when Docker is available.
  • up: requests detached startup and readiness; not yet validated on this host.
  • check: probes http://localhost:8080/debug/ready.
  • down: stops Compose without deliberately deleting database/bootstrap volumes; never run down -v on data you need.
  • The local identity seed email/username is described in core/backend/zitadel/README.md, but actual initial sign-in has never been verified.
  • Self-signed/local HTTP is for local development only; no public network ports or production data.

Account Portal OIDC client setup (NOT performed in P04)

  1. Create a dedicated confidential Web/OIDC app in a disposable ZITADEL environment, using Authorization Code + PKCE.
  2. Register the exact intended callback http://localhost:3001/api/auth/callback/zitadel for local development, or https://account.vib.tools/api/auth/callback/zitadel when production is explicitly deployed. Do not mix localhost callbacks into production.
  3. Inject secure runtime-only settings from users/ui/.env.example: ZITADEL_ISSUER, ZITADEL_CLIENT_ID, ZITADEL_CLIENT_SECRET, AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST.
  4. Keep confidential client secret and AUTH_SECRET server-side. Never use the backend master key, the official Login Client PAT or a browser-shared client secret as substitutes.
  5. CI must create/approve a deterministic Account Portal dependency lockfile and check Auth.js beta/Next.js compatibility, then build/typecheck on an isolated runner.
  6. Only after source/build acceptance, integrate Account Portal runtime, OIDC callbacks, HTTPS proxy headers and session behavior in a separately approved scope.
  7. Confirm end-to-end login, expiry, logout semantics, API 401/200 response and account self-service permissions in disposable staging.

Production domains auth.vib.tools and account.vib.tools are design targets only. Coolify configuration, TLS, persistent backup/restore, secure secret handling and production rollbacks are not implemented.

User account / password / MFA management

The Account Portal's profile page is currently read-only, and security page displays guidance/links. If ZITADEL self-service is enabled, users may be redirected to its built-in Console location; access is policy-dependent and not live-verified. Do not expect local Save Password, Enroll MFA, revoke device or account deletion buttons.

Administrator boundaries

ZITADEL Admin Console is distinct from the Account Portal. Never expose administrative API tokens or secrets to the browser. Identity administration should follow roles/policies, while billing/subscriptions/product permissions belong to individual SaaS applications.

Gitea Actions verification (P05-CI-01)

A manual-only workflow is defined in .gitea/workflows/p05-ci.yml. In Gitea go to vibtools/ZitPlane > Actions > ZitPlane P05 CI Verification > Run workflow (main). This runs on a registered Docker-capable ubuntu-latest runner, not your PC. See docs/P05-CI-01.md for its four gates and limitations. The CI workflow creates only disposable local test credentials and removes its own volumes; no real accounts, Coolify or production domains are accessed.

Acceptance and configuration troubleshooting

Refer to FEATURES-STATUS.md, TROUBLESHOOTING.md, docs/P02-EVIDENCE.md and docs/P04-ACCOUNT-PORTAL.md. Do not claim success on a missing-run check. Future changes must update all affected docs and developer records.

P05-CI-02 status (2026-11-22): Run #83 verified Account Portal build/typecheck and negative auth checks, Login V2 1219/1219 unit tests and a successful high/critical dependency threshold (Moderate issues still open). Disposable Postgres/ZITADEL API/Login V2 became healthy, but host TCP 8080 prevented proxy startup; cleanup succeeded. The workflow now has a CI-only portless override to allow internal-Docker-network probing on a shared runner, not yet rerun. See docs/P05-CI-02.md. This is not a production deployment guide.

P05-CI-03 backend-only runtime verification (Gitea only)

In Gitea vibtools/ZitPlane → Actions → ZitPlane P05-CI-03 Backend Acceptance → Run workflow → main. It uses the existing ubuntu-latest Linux Docker-capable runner; no Account or Login V2 production build suites are rerun. All credentials are generated in the disposable runner and are never used for production accounts. It checks portless effective Compose, four container states, a synthetic PostgreSQL restart marker, backend readiness, OIDC issuer/discovery and JWKS, and always-owned-resource cleanup. Results must come from the exact Gitea Actions run, not source presence. See docs/P05-CI-03.md. This is not full interactive login, Coolify or production deployment.

P05-CI-03 verified result: Gitea Run #86 SUCCESS on source SHA 03fb589. It confirmed the portless CI backend configuration, four-service readiness, PostgreSQL marker persistence after restart, ZITADEL OIDC discovery/JWKS and complete CI-owned cleanup. This does not mean the developer PC or production Coolify instance is configured, nor does it prove an authenticated user login/MFA. The run did not repeat earlier Account/Login builds. See docs/P05-CI-03.md for evidence.

P05-SEC-01 security acceptance on Gitea (manual only)

On Gitea vibtools/ZitPlane open Actions → ZitPlane P05-SEC-01 Dependency Security Acceptance → Run workflow on main after the approved source commit is pushed. Jobs use fresh CI runner containers, immutable committed npm/pnpm locks, and no production identity credentials. Account/official Login V2 reproducible builds and unit/negative regressions run separately from Account and Login registry audits. Audits fail if there is any Moderate, High or Critical finding; the script prints exact advisory IDs so an outstanding transitive dependency can be fixed in another explicit Scope Lock. The P02 developer Compose, local Windows PC and production Coolify are not modified. See docs/P05-SEC-01.md and project/DEPENDENCY-SECURITY.md.

P05-SEC-01 actual evidence: Run #87 verified Account/Login frozen dependency installs, production builds and 1219/1219 Login unit tests; the Account security audit is clean. However Login glob and minimatch each still have one Moderate advisory, and the strict security job correctly failed. Production usage and package-security acceptance remain blocked until separate transitive-remediation approval and CI. No local application tests or deployment.

P05-SEC-02 — focused Login-only dependency security acceptance

Gitea vibtools/ZitPlane → Actions → ZitPlane P05 Dependency Security Acceptance (SEC-01/02) → manual Run workflow on main, set login_only=true. This option deliberately skips Account build/security jobs already accepted in Run #87. Only the frozen official Login workspace install, source-level seven-override contract, proto/client/Next standalone build + upstream unit suite and live production pnpm vulnerability gate execute. The expected security threshold is 0 Moderate, 0 High, 0 Critical. The authenticated OIDC end-to-end flow and production deployment are not part of the dependency gate. See docs/P05-SEC-02.md.

P05-SEC-02 verified outcome: Gitea Run #88 with login_only=true proved a clean Login production registry audit (zero known Moderate/High/Critical), while Account jobs were correctly skipped. The Login build/unit job did not reach frozen install because a new CI helper misparsed >= version-range selectors; a post-run source-only parser correction is unverified. Do not deploy or claim Login dependency compatibility until the separately approved P05-SEC-02-A01 CI completes. No local build/test is required.

P05-SEC-02-A01 — one-run Login security/build verification

Use Gitea Actions → ZitPlane P05 Dependency Security Acceptance (SEC-01/02) → manual main workflow with login_only=true. Only Login frozen PNPM install, proto/client/Next standalone build, upstream Vitest and zero Moderate/High/Critical live registry audit should run. Account jobs should be skipped (Run #87 already accepted), and there is no backend, human identity or production deployment. A successful security audit alone is insufficient; the login build/unit job must also pass. Actual results will be in docs/P05-SEC-02-A01.md and notes/P05-SEC-02-A01.md.

P05-SEC-02-A01 VERIFIED: Gitea Run #89 succeeded with manual login_only=true: patched seven-parent dependency contract, pinned frozen PNPM install, proto/client/Login standalone production build, 1219/1219 upstream tests and production registry audit 0 Moderate/High/Critical. Account jobs were intentionally skipped. No user credential, interactive OIDC login, MFA, production TLS or deployment was tested; do not treat this as a deployed service.

P05-OIDC-01 — isolated real-user OIDC verification, Gitea only

In Gitea vibtools/ZitPlane → Actions → ZitPlane P05-OIDC-01 Disposable Real Browser Acceptance → manual Run workflow on main only when explicitly approved. The workflow provisions its own short-lived IAM_OWNER PAT, isolated ZITADEL project/client/verified test human, then tests the actual ZITADEL Login V2 username/password and Auth.js Account callback in Chromium. It does not use your real users, public domain, production secrets or host-published HTTP ports. It removes its test credentials, browser and isolated database/volumes via an always() step; any cleanup failure prevents phase acceptance. See docs/P05-OIDC-01.md for the expected checks and current real run result. This test uses CI-only HTTP loopback (Account development mode), not the actual production HTTPS issuer.

P05-OIDC-01 actual Gitea evidence: Run #90 started the original ZITADEL/PostgreSQL/Login V2/Traefik stack healthy without publishing host ports, but could not establish private localhost:8080 forwarding. Official OIDC project/client/user setup and real browser callback did not execute; overall CI FAILED. Mandatory owned-only resource cleanup PASSED. The run did not impact production or user accounts. A separately scoped P05-OIDC-02 CI network-forwarder acceptance is needed before claiming interactive OIDC works.

P05-OIDC-02 procedure: Reuse the existing manual ZitPlane P05-OIDC-01 Disposable Real Browser Acceptance Gitea workflow (file .gitea/workflows/p05-oidc-acceptance.yml) with the newly patched CI-only forwarder. A good run first validates private proxy Host routing, prebuilt alpine/socat:1.8.1.3 image digest and forwarded localhost:8080 HTTP 200, then provisions disposable OIDC client/user and tests a real Chromium/Account Portal callback before always-run cleanup. No host ports, no real credentials, no local tests. Actual PASS/BLOCKED will be recorded in docs/P05-OIDC-02.md and notes/P05-OIDC-02.md.

P05-OIDC-02 actual Gitea status: Run #91 FAILED after original ZITADEL 4-service startup, private proxy Host routing and socat image verification all PASS. The private forwarder container exited with code 1, preventing disposable OIDC client/user and browser login. Every authentication/callback/session assertion remains NOT EXECUTED; mandatory cleanup PASS. Do not manually add users or open network ports. See docs/P05-OIDC-02.md; a separate P05-OIDC-03 approval is required for CI-only forwarder startup diagnostics.

P05-OIDC-03 acceptance: The existing manual p05-oidc-acceptance.yml on a dedicated Gitea Docker runner will first classify the disposable socat startup and, if unhealthy, start a digest-verified official Python-only 127.0.0.1:8080 loopback forwarder within the same private proxy namespace. It then must prove the original official OIDC client/user + real Chromium Login V2/Account callback/session/negative contracts and owned-resource teardown. This changes no production secrets, identity settings, Login/Auth.js code or published host ports. Actual PASS/BLOCKED status is in notes/P05-OIDC-03.md.

P05-OIDC-03-A02 terminal result: Run #93 started and FAILED, so the previous “runner queued” blocker is no longer current. Four-service portless ZITADEL stack and private Traefik routing worked; socat and Python fallback both failed binding private TCP port 8080 (SOCKET_BIND_ERROR / ADDRESS_IN_USE). Neither official test OIDC client/user nor actual Chromium Login V2/Auth.js session was exercised; mandatory cleanup PASS. No changes to this setup or production. Inspect verified socket ownership only in a separately approved disposable CI before selecting a network/port remedy. See docs/P05-OIDC-03-A02.md.

P05-OIDC-04 terminal guidance: Run #95 used a scoped separate run-owned private forwarder namespace candidate without publishing host ports or modifying original Compose. However it FAILED before forwarder startup at the direct Traefik private Host socket/HTTP check despite four healthy containers. Socket-owner diagnostics, official client/user provisioning and real Login V2/Auth.js authentication NOT EXECUTED; mandatory owned-only cleanup PASS. Do not change local/production configs or manually create test accounts. Next action requires a new, narrowly approved direct-proxy-readiness RCA. See P05-OIDC-04.md.

P05-OIDC-04-A01 acceptance: Gitea Run #96 SUCCESS, not a production installation. In disposable CI, private Host/forwarder and full original Login V2 → Auth.js → Account protected session/identity API → negative cases → portal logout passed; owned credentials/database/containers/network cleanup verified. Traefik PID1 was actually listening on proxy-local TCP6:8080; the isolated forwarder avoids binding in that shared namespace. Do not expose port 8080, use real test humans, modify production secrets or infer that custom imported Login V2, MFA/passkeys or HTTPS has been accepted. See P05-OIDC-04-A01.md.