Rewrite project documentation

docs/deployment.md

@@ -0,0 +1,60 @@
+# Deployment und Betrieb
+
+## Aktueller Status
+
+Es gibt derzeit kein unterstütztes Produktionsdeployment.
+
+`compose.yaml` ist ausschließlich für lokale Entwicklung vorgesehen. Es startet
+`tsx watch` und `next dev`, bindet Quellcode vom Host ein und enthält weder TLS,
+Authentifizierung, Reverse Proxy, Prozesshärtung noch ein zentral betriebenes
+Datenbanksystem. Der Stack darf deshalb nicht als produktionsreif bezeichnet oder
+öffentlich erreichbar gemacht werden.
+
+## Entwicklungs-Topologie
+
+| Komponente | Port | Healthcheck | Persistenz |
+| --- | ---: | --- | --- |
+| Next.js Web | 3001 | `GET /` | keine |
+| Express API | 3000 | `GET /health` | `./data:/app/data` |
+| SQLite | Datei | Integritäts-/FK-Prüfung via Backup und Skript | `data/leistungsbilanz.db` |
+
+Verwendete Umgebungsvariablen:
+
+- `PORT` – API-Port, Standard `3000`
+- `API_INTERNAL_URL` – internes API-Ziel des Next.js-Rewrites, im Compose-Netz
+  `http://api:3000`
+- `NEXT_TELEMETRY_DISABLED=1`
+- `CHOKIDAR_USEPOLLING=true` und `WATCHPACK_POLLING=true` für lokale
+  Dateibeobachtung in Docker
+
+Beim API-Start laufen zuerst `npm run db:migrate` und
+`npm run db:verify:circuit-schema`.
+
+## Voraussetzungen für ein späteres Produktionssetup
+
+Vor einer produktiven Installation werden mindestens benötigt:
+
+- reproduzierbare Produktionsimages und ein Next.js-Produktionsstartskript
+- TLS-Termination und Reverse Proxy
+- Authentifizierung, Autorisierung und Benutzer-/Rollenmodell
+- definierte Secrets- und Konfigurationsverwaltung
+- persistenter, gesicherter Datenbankbetrieb
+- kontrollierter einmaliger Migrationsschritt vor dem API-Rollout
+- Monitoring, strukturierte Logs und Alarmierung
+- getestete Backup-, Restore- und Rollback-Prozeduren
+- Entscheidung, ob SQLite für einen einzelnen Prozess genügt oder PostgreSQL für
+  Mehrbenutzerbetrieb erforderlich ist
+
+Bis diese Punkte umgesetzt und getestet sind, besteht die „Installation“ aus dem
+lokalen Entwicklungsstart in der README.
+
+## Backup und Wiederherstellung
+
+`npm run db:backup` erzeugt unter `data/backups/` ein konsistentes SQLite-Backup,
+öffnet es unabhängig und prüft Integrität sowie Fremdschlüssel. Diese
+Dateisicherungen sind von zukünftigen logischen Projektversionen getrennt.
+
+Eine produktive Restore-Anweisung wird erst zusammen mit einem unterstützten
+Produktionsbetrieb veröffentlicht. Lokale Wiederherstellung darf nur bei
+gestoppter API, gegen eine separate Datei und nach erneuter Integritätsprüfung
+erfolgen.