40 lines
3.9 KiB
Markdown
40 lines
3.9 KiB
Markdown
# 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.
|