# Deployment und Betrieb

Die Anwendung wird als ein Docker-Image ausgeliefert. Das Image enthaelt das
gebaute NestJS-Backend und das gebaute Angular-Frontend.

## Release-Build

Vor jedem Release:

```bash
npm ci
npm run lint
npm run format:check
npm run typecheck
npm test
npm run build
docker build -t registry.example.com/business-app:<tag> .
```

`npm run build` fuehrt aus:

1. API-Client generieren
2. API-Client bauen
3. Backend bauen
4. Frontend bauen
5. Frontend nach `apps/backend/dist/public` kopieren

Das Dockerfile baut erneut im Container und erzeugt anschliessend ein schlankes
Runtime-Image mit Non-Root-User.

## Runtime-Konfiguration

Konfiguration erfolgt ueber Umgebungsvariablen. Nutze `.env.example` nur als
Vorlage. Production-Secrets gehoeren in Secret Management, CI/CD Variables oder
eine geschuetzte Server-Konfiguration.

Wichtige Produktionswerte:

- `NODE_ENV=production`
- `APP_BASE_URL=https://app.example.com`
- `FRONTEND_BASE_URL=https://app.example.com`
- `TRUST_PROXY=true`, wenn hinter Reverse Proxy
- `DATABASE_SSL=true`, wenn die Datenbank TLS erzwingt
- `SWAGGER_ENABLED=false`, ausser bewusst anders entschieden
- starke Werte fuer `SESSION_SECRET`, `SESSION_ENCRYPTION_KEY`, `OIDC_CLIENT_SECRET`

## Migrationen

Migrationen werden nicht beim App-Start ausgefuehrt. Fuehre sie vor dem neuen
App-Container aus, mit demselben Image und derselben Konfiguration:

```bash
docker run --rm --env-file .env registry.example.com/business-app:<tag> node apps/backend/dist/database/run-migrations.js
```

Danach den App-Container starten oder aktualisieren. Wenn Migrationen fehlen,
schlaegt der App-Start fehl beziehungsweise `/health/ready` bleibt nicht bereit.

## Container starten

Ein einfaches Compose-Beispiel liegt in `compose.yml`:

```bash
docker compose up -d
```

Der Container:

- laeuft als Non-Root-User
- verwendet ein read-only Root Filesystem
- nutzt `/tmp` als tmpfs
- dropt Linux Capabilities
- prueft `/health/ready` als Healthcheck

Compose baut oder nutzt das Image `internal-business-app:latest`. Fuer echte
Deployments sollte ein versioniertes Registry-Image verwendet werden.

## Reverse Proxy

Nginx oder ein Load Balancer sollte TLS terminieren und alle Routen an den
App-Container weiterleiten. Die Angular-Dateien werden nicht separat durch Nginx
ausgeliefert. Ein Beispiel liegt in `docs/nginx-example.conf`.

Wichtig:

- WebSocket-Konfiguration ist fuer dieses Boilerplate nicht erforderlich.
- `X-Forwarded-Proto` und `X-Forwarded-For` sollten gesetzt werden.
- `APP_BASE_URL` muss zur externen HTTPS-URL passen.
- Wenn `TRUST_PROXY=true` gesetzt ist, muss der Proxy vertrauenswuerdig sein.

## Healthchecks

- `/health/live`: Prozess lebt.
- `/health/ready`: Datenbank erreichbar, Migration-Check initialisiert und keine
  offenen Migrationen.

Readiness ist der richtige Check fuer Rolling Deployments und Container
Orchestrierung.

## TeamCity-Beispiel

1. Checkout
2. `npm ci`
3. `npm run lint`
4. `npm run format:check`
5. `npm run typecheck`
6. `npm test`
7. `npm run build`
8. `docker build -t <registry>/<image>:<build-number> .`
9. `docker push <registry>/<image>:<build-number>`
10. Migration-Job mit neuem Image ausfuehren
11. App-Service auf neues Image aktualisieren
12. `/health/ready` pruefen

## Rollback

Ein Rollback ist nur dann einfach, wenn die Datenbankmigrationen rueckwaerts
kompatibel geplant wurden. Fuer riskante Schema-Aenderungen sollte das Expand-
Contract-Muster verwendet werden:

1. Neue Spalten oder Tabellen hinzufuegen, alte weiter bedienen.
2. Anwendung umstellen.
3. Daten migrieren.
4. Alte Spalten oder Pfade in einem spaeteren Release entfernen.

## Betrieb

Beobachte mindestens:

- HTTP-Fehlerraten und Latenzen
- Healthcheck-Status
- Datenbankverbindungen
- Login-Fehler vom OIDC Provider
- `MIGRATION_MISSING`
- Rate-Limit-Treffer, insbesondere `RATE_LIMIT_EXCEEDED` auf Login- und Admin-Endpunkten
- Audit-Log fuer administrative Aktionen

Logs sollten zentral gesammelt werden. Request IDs helfen dabei, Frontend-Fehler,
Backend-Logs und Audit-Eintraege zusammenzufuehren.