Files
ZitPlane/docs/SETUP-GUIDE.md
T

4.9 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.

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.