docs: Installationsanleitung Schritt fuer Schritt

Die README hatte Installationsabschnitte, aber keine durchgehende
Anleitung fuer jemanden, der vor einem frischen Server sitzt. Genau da
faengt diese hier an.

Dreizehn Schritte vom leeren Server bis zur laufenden Anwendung, jeder
mit einer Kontrolle am Ende - man geht nicht weiter, ohne geprueft zu
haben, ob der letzte Schritt geklappt hat. Am Ende eine Abnahmeliste
zum Abhaken, bevor echte Daten hineinkommen.

Aufgenommen sind die Fallstricke, die tatsaechlich Zeit kosten:

- AV-Vertrag klaeren, BEVOR der Server bestellt wird
- Zeitzone setzen, sonst rechnet der Server in UTC und verschiebt Fristen
- AUTH_URL muss exakt der aufgerufenen Adresse entsprechen - sonst landet
  die Anmeldung stumm wieder auf dem Formular, ohne Fehlermeldung. Das
  ist der Fehler, den man am laengsten sucht.
- Der Proxy muss X-Forwarded-For weiterreichen, sonst zaehlt die
  Login-Sperre alle Zugriffe als denselben Anschluss.
- Die beiden SQL-Skripte laufen nicht mit den Migrationen mit.

Zwei Kontrollen sind keine Formalie, sondern Nachweise: Der Schutz des
Audit-Logs wird geprueft, indem ein UPDATE ausdruecklich fehlschlagen
MUSS. Und die Sicherung wird nicht nur angestossen, sondern einmal
zurueckgespielt - solange noch nichts drinsteht, was weh tut.

Der letzte Schritt bringt ENC_KEY_V1 in Sicherheit, an zwei Orte, von
denen keiner der Server ist. Ein gestohlenes Backup ist ohne ihn
wertlos - und ein verlorener Schluessel macht auch das eigene Backup
wertlos. Das ist dieselbe Eigenschaft von zwei Seiten.

Etappe: 8
Phase: Haertung
This commit is contained in:
Florian Wilde
2026-08-22 10:54:21 +02:00
parent 0e7da42f27
commit 89bc5fe5a8
2 changed files with 822 additions and 0 deletions
+23
View File
@@ -15,6 +15,7 @@ eines Angehörigen: Fristen, Vorgänge, Belege, Vermögen, Sozialhilfe, Berichte
## Inhalt
- [Was die Anwendung kann](#was-die-anwendung-kann)
- [Die drei Dokumente, die du wirklich brauchst](#die-drei-dokumente-die-du-wirklich-brauchst)
- [Schnellstart zum Ausprobieren](#schnellstart-zum-ausprobieren)
- [Produktivbetrieb mit Docker Compose](#produktivbetrieb-mit-docker-compose)
- [Reverse Proxy](#reverse-proxy)
@@ -46,6 +47,23 @@ eines Angehörigen: Fristen, Vorgänge, Belege, Vermögen, Sozialhilfe, Berichte
---
## Die drei Dokumente, die du wirklich brauchst
| Wofür | Wo |
|---|---|
| **Einen Server aufsetzen** — von der leeren Maschine bis zur laufenden Anwendung, mit Kontrolle nach jedem Schritt | [`docs/INSTALLATION.md`](docs/INSTALLATION.md) |
| **Täglich damit arbeiten** — die zwölf Handgriffe, der Jahresrhythmus, was tun wenn etwas schiefgeht | [`docs/ANLEITUNG.md`](docs/ANLEITUNG.md), in der Anwendung unter `/anleitung` |
| **Wissen, was sich ändert** — was neu ist, was du vor einem Update beachten musst | [`CHANGELOG.md`](CHANGELOG.md) |
Dazu: [`docs/ROADMAP.md`](docs/ROADMAP.md) für das, was als Nächstes
kommt, und [`docs/BAUPROTOKOLL.md`](docs/BAUPROTOKOLL.md) für die Frage,
wie das hier entstanden ist.
Der Rest dieser Datei ist die Kurzfassung für alle, die schon wissen, was
sie tun.
---
## Schnellstart zum Ausprobieren
Voraussetzungen: **Node.js ≥ 20.11**, **Docker** und **Git**.
@@ -113,6 +131,10 @@ laufender Antrag beim Bezirk Oberfranken mit acht Nachforderungen.
## Produktivbetrieb mit Docker Compose
> **Zum ersten Mal?** Nimm die [Schritt-für-Schritt-Anleitung](docs/INSTALLATION.md).
> Sie fängt beim leeren Server an, hat nach jedem Abschnitt eine Kontrolle
> und endet mit einer Abnahmeliste. Was hier steht, ist die Kurzfassung.
Das Compose-Setup bringt drei Dienste mit: die Anwendung, PostgreSQL und
MinIO als S3-kompatiblen Objektspeicher, dazu einen Sicherungsdienst.
@@ -479,6 +501,7 @@ npm test # Vitest: Fachlogik
npm run test:e2e # Playwright: kritische Abläufe
npm run db:studio # Prisma Studio
npm run protokoll # Bauprotokoll aus der Git-Historie
npm run version -- patch # Version anheben, Changelog vorbereiten
```
Konventionen — verbindlich für alle Beiträge: