65 lines
4.9 KiB
Markdown
65 lines
4.9 KiB
Markdown
# 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):
|
|
|
|
```powershell
|
|
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](FEATURES-STATUS.md), [TROUBLESHOOTING.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.
|