89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# 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
|
|
```
|
|
|
|
## 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.
|