Initial commit

docs/getting-started.md

@@ -0,0 +1,93 @@
+# Getting Started
+
+Diese Anleitung bringt eine lokale Entwicklungsumgebung fuer das Boilerplate zum
+Laufen. Sie setzt voraus, dass MySQL 8 und ein OIDC Provider bereits verfuegbar
+sind.
+
+## Voraussetzungen
+
+- Node.js `24.18.0` aus `.nvmrc`
+- npm `11.x`
+- Docker fuer Image-Builds und spaetere Auslieferung
+- MySQL 8 mit `utf8mb4`
+- OIDC Client mit Authorization Code Flow, PKCE und Discovery Endpoint
+
+Das Repository ist ein npm-Workspace-Monorepo. Abhaengigkeiten werden immer aus
+dem Root installiert.
+
+```bash
+npm ci
+cp .env.example .env
+```
+
+## Lokale Konfiguration
+
+Trage in `.env` mindestens folgende Werte ein:
+
+- `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USER`, `DATABASE_PASSWORD`
+- `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`
+- `SESSION_SECRET` mit mindestens 32 zufaelligen Zeichen
+- `SESSION_ENCRYPTION_KEY` mit mindestens 32 zufaelligen Zeichen
+- `APP_BASE_URL=http://localhost:3000`
+- `FRONTEND_BASE_URL=http://localhost:4200`
+- `CORS_ORIGINS=http://localhost:4200,http://localhost:3000`
+
+Der OIDC Provider muss als Redirect URI diese URL erlauben:
+
+```text
+http://localhost:3000/api/auth/callback
+```
+
+Falls der Provider RP-Initiated Logout validiert, muss ausserdem
+`http://localhost:4200` beziehungsweise die konfigurierte `FRONTEND_BASE_URL` als
+Post-Logout-Redirect erlaubt sein. Wenn Discovery keinen `end_session_endpoint`
+liefert, setze `OIDC_LOGOUT_URL`.
+
+## Datenbank vorbereiten
+
+Die Anwendung fuehrt Migrationen beim normalen Start nicht automatisch aus.
+Fuehre sie bewusst aus:
+
+```bash
+npm run migration:status
+npm run migration:run
+```
+
+Wenn Migrationen fehlen, verweigert das Backend den Start beziehungsweise
+`/health/ready` bleibt nicht bereit.
+
+## Entwicklung starten
+
+```bash
+npm run dev
+```
+
+Das startet:
+
+- Frontend: `http://localhost:4200`
+- Backend: `http://localhost:3000`
+- API: `http://localhost:3000/api`
+- Health: `http://localhost:3000/health/live` und `/health/ready`
+- Swagger, falls `SWAGGER_ENABLED=true`: `http://localhost:3000/api/docs`
+
+Das Frontend proxyt `/api` ueber `apps/frontend/proxy.conf.json` an das Backend.
+Dadurch kann lokal mit Cookie-basierter Authentifizierung gearbeitet werden.
+
+## Erster Login
+
+1. Oeffne `http://localhost:4200`.
+2. Melde dich ueber den OIDC Provider an.
+3. Der erste lokal angelegte Benutzer erhaelt automatisch die Rollen `user` und
+   `admin`.
+4. Weitere Benutzer erhalten initial die Rolle `user`.
+
+Systemrollen und Permissions werden beim Login synchronisiert. Permissions sind
+im Code definiert und werden nicht frei in der UI angelegt.
+
+## Haefige Probleme
+
+- `Ungueltige Konfiguration`: `.env` verletzt das Schema in `apps/backend/src/config/env.ts`.
+- `MIGRATION_MISSING`: `npm run migration:run` ausfuehren.
+- `UNAUTHORIZED`: Session abgelaufen, Benutzer deaktiviert oder OIDC-Konfiguration falsch.
+- `CSRF_INVALID`: Schreibender Request ohne `X-CSRF-Token`; im Angular-Client erledigt das der Interceptor.
+- OIDC Callback schlaegt fehl: Redirect URI, Issuer, Client Secret und erlaubte Algorithmen pruefen.