Files
ZitPlane/project/SETUP-AND-DEPENDENCIES.md
T

3.9 KiB

Setup, modules and dependency rationale

Baseline: P04 source, Git 40af500; runtime not verified.

Technology / module Actual source location Why it exists / configured version
ZITADEL Go server Official Docker image in deployment/docker/compose.backend.dev.yaml Central IAM/OIDC/security policy server, pinned v4.20.4; Go source is not vendored
ZITADEL Login V2 auth/ui/v2/apps/login/ Original customisable Next.js login/recovery/MFA frontend, upstream tag v4.20.4; import-only
ZITADEL JS client/protos auth/ui/v2/packages/zitadel-client, zitadel-proto, proto Matched Login V2 generated API types/client and source protocol definitions
pnpm + Nx auth/ui/v2/package.json, lockfile, nx.json Original upstream Login V2 multi-package build chain; root workspace pins pnpm@10.30.3, imported Login package pins a different pnpm@10.28.2 in its manifest; compatibility to verify in future CI
Next.js / React users/ui/package.json Account Portal App Router and server components; next@16.4.3, react@19.2.6
Auth.js 5 / ZITADEL provider users/ui/src/auth.ts, package.json OIDC Authorization Code + PKCE, state, nonce and portal-local JWT sessions; next-auth@5.0.0-beta.32; compatibility/security CI pending
PostgreSQL P02 Compose ZITADEL storage, postgres:17.10-alpine
Traefik P02 Compose Local HTTP/2 h2c proxy, traefik:v3.7.7
Python stdlib helper core/backend/zitadel/dev.py Secure local secret generator, Compose wrapper, ready check; requires Python 3.10+ according to prior docs

Exact local development entrypoint (P02 only; no claim it ran)

From project root: py core/backend/zitadel/dev.py init (writes ignored .env once); config, up, ps, check, down subcommands require Docker. The production configuration is not built or deployed.

In deployment/docker/compose.backend.dev.yaml, named volumes postgres-data and zitadel-bootstrap preserve DB and bootstrap token. Proxy only publishes 127.0.0.1:8080:80. Local ZITADEL admin username is zitadel-admin@zitadel.localhost, initial password generated in ignored .env; no real user account setup has been verified.

Account portal environments (not provisioned)

users/ui/.env.example documents ZITADEL_ISSUER, ZITADEL_CLIENT_ID, ZITADEL_CLIENT_SECRET, AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST. All must be securely provisioned before a live OIDC session can work. Proposed callback: /api/auth/callback/zitadel, matching dedicated confidential ZITADEL Web client.

The Account Portal has no dependency lockfile yet. npm ci/reproducible build is unavailable until a separately approved lockfile/CI phase. The P03 slim workspace retains the original upstream pnpm-lock.yaml with unverified frozen-install compatibility.

Why modules live where they do

  • core/ contains ZitPlane orchestration, not a ZITADEL Go fork; updates to Go backend are done by deliberate image upgrades.
  • auth/ retains upstream source-relative layout to avoid breaking shared imports and make merge/supply-chain audits possible.
  • users/ui/ is a separate product surface because account self-service is not the same as login/challenge flows.
  • deployment/ separates local infrastructure from a future production Compose/Coolify stack.
  • packages/ is a placeholder for future ZitPlane-owned reusable UI; do not confuse with auth/ui/v2/packages/ which are pinned upstream dependencies.
  • notes/ = phase plans/evidence; project/ = developer truth; docs/ = user guides.

Pending checks before any release

Version security review, reproducible installs, TypeScript/typecheck, Next.js build, OIDC state/PKCE, callback, token expiry, local vs global logout, self-service access, routing, secrets handling, production TLS, backup/restore, monitoring, and isolated Gitea CI verification. No current public deployment exists per recorded phase evidence.