Florian WildeandClaude Opus 5
f3950847f3
Neben "Drucken" steht am Lauf "Als PDF", im Archiv an jedem Treffer "Protokoll als PDF" — dasselbe Blatt als fertige Datei, zum Verschicken oder Abheften. Unten darauf jetzt zwei Unterschriftsfelder mit Zeile fuer Ort, Datum und Namen; wo eine Vier-Augen-Freigabe erteilt wurde, steht sie mit im Kopf. Erzeugt wird es, indem der Server seine eigene Druckansicht ueber 127.0.0.1 laedt und druckt — mit dem Sitzungscookie des Anfragenden. Damit gibt es genau eine Vorlage fuer Papier und Datei, und fuer das PDF gilt dieselbe Rechte- und Mandantenpruefung wie fuer die Seite. Ein zweites Layout waere billiger und wuerde frueher oder spaeter abweichen, ohne dass es jemandem auffaellt. Ein eigener Browser-Kontext je PDF, kein geteilter: er traegt die fremde Sitzung, und ein geteilter gaebe sie an das naechste PDF weiter. Gespeichert wird nichts — ein abgelegtes PDF waere eine zweite Wahrheit neben dem Lauf. Ein erzeugtes Passwort steht auch hier nie darauf, geprueft am extrahierten Text des fertigen PDF und nicht an den Bytes: der Inhalt ist komprimiert, dort nichts zu finden bewiese nichts. Chromium bleibt optional, und die gemessene Zahl ist der Grund: das Laufzeitbild waechst von 370 MB auf 1,52 GB, Alpines chromium kostet allein 1,13 GB. Er kommt nur mit `--build-arg MIT_PDF=1` beziehungsweise `deploy/install.sh --mit-pdf` mit. Fehlt er, erscheint der Knopf gar nicht erst — ein Knopf, der zuverlaessig in eine Fehlermeldung fuehrt, ist schlimmer als keiner. Ein direkter Aufruf bekommt 503 mit einer Meldung, die sagt, was fehlt und wo es steht; ein leeres PDF gibt es in keinem Fall. Meine Schaetzung lag um das Dreieinhalbfache daneben: "+328 MB" war das .apk-Paket, nicht das Bild, und stand schon im Dockerfile-Kommentar, bevor ich gebaut hatte. Jetzt steht die gemessene Zahl an drei Stellen. 1545 Vitest-Tests (vorher 1526): 15 in tests/pdf.test.ts, die den Handler echt fahren, 3 in tests/pdf-grenze.test.ts fuer die Obergrenze mit gestelltem Browser, einer in tests/archiv.test.ts. Dazu drei E2E-Ablaeufe; volle Suite gruen mit 118 bestanden. Ein Blatt wurde wirklich erzeugt und angesehen. Sechs Gegenproben, alle angeschlagen — darunter ein echtes Passwort auf dem Blatt und die Freigabe des Zaehlers aus dem finally genommen, der Fall, in dem ein Fehlschlag die PDF-Erzeugung bis zum Neustart leise stilllegt. Closes #41 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Laufzettel betreiben
Diese Sammlung richtet sich an den, der Laufzettel betreibt, aber nicht gebaut hat. Sie führt von einem leeren Server bis zur ersten Anmeldung, und danach durch Aktualisierung, Sicherung und Fehlersuche. Wer die Anwendung benutzen will, liest stattdessen die Anleitung.
Es gibt zwei Wege in den Betrieb. Beide sind gleichwertig und führen zum selben Stand.
| Weg | Für wen | Was du mitbringen musst |
|---|---|---|
| Docker Compose | Es gibt schon einen Docker-Host, und weitere Dienste laufen dort ebenso. Aktualisieren heißt neu bauen. | Docker mit Compose-Plugin |
| Nativ im Proxmox-LXC | Es gibt einen Proxmox-Host und keinen Docker. Ein Skript legt den Container an und installiert darin alles — PostgreSQL, Node, die Anwendung, einen systemd-Dienst. | Proxmox VE 8 oder 9, oder ein leeres Debian 13 |
Nimm den Compose-Weg, wenn du schwankst: er ist der Weg, gegen den hier entwickelt und getestet
wird. Der pct-Teil des Proxmox-Skripts ist ungetestet — das steht so, und warum, in
proxmox.md.
Was auf beiden Wegen gilt
Vier Dinge sind keine Empfehlung, sondern Teil des Aufbaus. Sie zu übergehen heißt, einen anderen Stand zu betreiben als den beschriebenen.
Die Datenbank ist von außen nicht erreichbar. Im Compose-Stand hat postgres kein
ports:-Mapping und hängt nur im Netz intern, das internal: true ist — ein Netz ohne Gateway.
Nativ läuft PostgreSQL mit listen_addresses = '', also nur am Unix-Socket. Dieselbe Regel, zwei
Mittel. Daraus folgt, dass jede Sicherung und jeder Blick in die Daten über den Dienstnamen
beziehungsweise den Socket läuft, nie über psql -h localhost. tests/betriebsstand.test.ts hält
das für den Compose-Stand fest, damit ein ports:-Mapping nicht versehentlich zurückkommt.
Die Anwendung bindet auf 127.0.0.1 und spricht kein HTTPS. Davor gehört ein Reverse Proxy, der
das Zertifikat hält — siehe reverse-proxy.md. Ohne Proxy erreicht die
Anwendung niemand außer dem Host selbst, und das ist die richtige Voreinstellung: ein Dienst, der
aus Versehen im LAN steht, fällt keinem auf.
APP_URL ist die öffentliche Adresse und wird nicht geraten. Aus ihr entstehen die QR-Adressen
auf den gedruckten Aufklebern und die OIDC-Rücksprungadresse. Sie später zu ändern ist möglich, aber
teuer — der Grund steht am Anfang von reverse-proxy.md. Leg die Adresse fest,
bevor der erste Aufkleber gedruckt wird.
Geheimnisse entstehen im Zielsystem. APP_SECRET, das Datenbank-Passwort und das erste
Admin-Passwort werden dort erzeugt, wo sie gelten, und stehen in keinem Repository und in keiner
Vorlage. APP_SECRET gehört mit in die Sicherung: ohne ihn sind nach dem Zurückspielen alle
Sitzungen ungültig und die verschlüsselt gespeicherten LDAP-Bind-Passwörter unlesbar. Siehe
sicherung.md.
Die Kapitel
- Inbetriebnahme mit Docker Compose — von null bis zur ersten Anmeldung, mit der vollständigen Tabelle der Umgebungsvariablen, dem Seed und der Aktualisierung
- Der native Weg im Proxmox-LXC —
deploy/proxmox/laufzettel.shunddeploy/install.sh, was sie anlegen, wie ein zweiter Aufruf aktualisiert, und die Prüfliste für den ersten echten Lauf - Reverse Proxy — Caddy und nginx als vollständiges Beispiel, TLS, Weiterleitungen, welche Kopfzeilen nötig sind und welche schaden
- Anmeldung über authentik — OIDC-Provider, Gruppen auf Rollen, Notfallzugang
- Sichern und Zurückspielen — auf beiden Wegen, was in die Sicherung gehört und was nicht, und wie du prüfst, dass das Zurückspielen wirklich funktioniert
- Entra ID als Verzeichnisquelle — App-Registrierung,
User.Read.All, Administratoreinwilligung, und was anders ist als bei einem lokalen AD - Benachrichtigungen — SMTP einrichten, den Webhook prüfen, die Signatur nachrechnen, und wo man nachsieht, wenn keine Mail mehr ankommt
- SCIM-Endpunkt — die einzige Stelle, an der ein fremder Dienst von außen schreibend zugreift: das Token, was nicht unterstützt wird, und was der Reverse Proxy durchlassen muss
- Das Übergabeprotokoll als PDF — eine Zusatzausstattung, die Chromium verlangt und das Bild von 370 MB auf 1,52 GB bringt: wann sie sich lohnt, wie sie dazukommt, und was passiert, wenn man sie weglässt
Wo sonst noch etwas steht
../../README.md— Kurzfassung für Entwickler, Betriebsmodi, Seed-Inhalt../../.env.example— jede Umgebungsvariable mit Kommentar, zum Kopieren../architektur.md— warum es so gebaut ist; Abschnitt 6 fasst die Betriebsregel zusammen../anleitung/08-fehlerbehebung.md— Fehlermeldungen der Oberfläche. Wer eine Meldung im Browser sieht, ist dort besser bedient als hier