boilerplate/docs/getting-started.md

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.

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:

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:

npm run migration:status
npm run migration:run

Wenn Migrationen fehlen, verweigert das Backend den Start beziehungsweise /health/ready bleibt nicht bereit.

Entwicklung starten

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.