morz-infoboard/TECH-STACK.md

Info-Board Neu - Tech Stack

Ziel

Dieses Dokument zieht die Technologieentscheidungen verbindlich zusammen, damit sie nicht nur verteilt in Plan und Todo-Liste stehen.

Leitlinien:

• moeglichst wenige Laufzeitabhaengigkeiten
• gute Portabilitaet zwischen Raspberry Pi OS und Debian
• einfache Verteilung per Ansible
• robuste Offline-Faehigkeit
• moeglichst wenig Ballast auf den Playern

Verbindliche Entscheidungen

Betriebssysteme

• Player: aktuelles Raspberry Pi OS Lite auf Debian-13-Basis
• Server: Debian-artiges System, bevorzugt mit Docker Compose betrieben

Display-Stack auf dem Player

• Version 1 basiert auf X11
• keine volle Desktop-Umgebung
• kein LXDE, kein LightDM als Pflichtbestandteil
• Chromium laeuft im Kiosk-Modus gegen eine lokale Player-Oberflaeche

Begruendung:

• X11 ist fuer Chromium-Kiosk auf Raspberry Pi aktuell konservativer und besser vorhersehbar als Wayland
• weniger Ueberraschungen bei Screenshot-Erzeugung, Display-Steuerung und Watchdog-Verhalten

Programmiersprachen

• Go ist die bevorzugte Sprache fuer systemnahe Komponenten
• Go ist die Standardwahl fuer den player-agent
• Go ist die bevorzugte Sprache fuer das Server-Backend, solange keine zwingenden Gruende dagegensprechen
• Browser-Oberflaechen werden mit einem normalen Web-Frontend-Stack umgesetzt

Begruendung:

• statische oder weitgehend selbstgenuegsame Binaries
• geringe Laufzeitabhaengigkeiten
• gute Cross-Compile- und Deploy-Eigenschaften
• passend fuer Debian- und Raspberry-Pi-Umgebungen

Frontend-Stack

• Admin-UI: Web-Anwendung
• Tenant-/Monitor-UI: Web-Anwendung
• Player-UI: lokale Web-Anwendung fuer den Renderer

Noch offen, aber bewusst klein zu halten:

• Framework-Auswahl fuer Server-UIs, bevorzugt leichtgewichtig
• keine unnötig schwere Fullstack-Plattform nur aus Gewohnheit

Server-Betrieb

• zentrale Komponenten bevorzugt in Docker Compose
• getrennte Services fuer Backend, Datenbank, MQTT und Reverse Proxy
• persistente Daten ausserhalb fluechtiger Container-Dateisysteme
• Provisionierungsjobs laufen serverseitig ueber einen dedizierten Worker oder Jobrunner

Player-Betrieb

• keine Voll-Containerisierung des Grafikpfads in Version 1
• native systemd-Dienste fuer player-agent und Browser-Startlogik
• lokale Verzeichnisse fuer Cache, Medien, Status und Logs

Provisionierung und Deployment

• die technische Erstinstallation neuer Screens wird ueber SSH + Ansible umgesetzt
• das Admin-Backend ist die steuernde Oberflaeche, aber nicht der Ort fuer eigentliche Shell-Logik
• Root-Passwoerter dienen nur als Bootstrap-Mittel und sollen nicht dauerhaft gespeichert werden
• nach der Erstinstallation erfolgt die weitere Verwaltung schluesselbasiert

Zielkomponenten

Player

• player-agent in Go
• player-ui als lokale Web-Oberflaeche
• Chromium als Renderer
• Xorg-Minimalstack
• systemd fuer Start, Neustart und Watchdog-Integration

Server

• Backend-API in Go
• Admin-UI als Web-Frontend
• Tenant-UI als Web-Frontend
• PostgreSQL
• MQTT-Broker, bevorzugt Mosquitto
• Reverse Proxy
• Dateispeicher fuer Uploads, Caches und Screenshots

Kommunikationsstack

• HTTPS fuer API, Upload, Download, Authentifizierung und Screenshots
• MQTT fuer Heartbeat, Status, Kommandos und Acknowledgements

Nicht vorgesehen:

• Medienuebertragung ueber MQTT
• permanente Spezial-Streams fuer den Regelbetrieb

Laufzeit-Minimum auf dem Player

Anzustreben sind nur diese grossen Bausteine:

• Raspberry Pi OS Lite
• Xorg-Minimalstack
• Chromium
• eigenes Go-Binary fuer den Agenten
• systemd

Moeglichst zu vermeiden:

• komplette Desktop-Umgebungen
• mehrere externe Viewer wie feh, vlc, wmctrl, xdg-open
• umfangreiche Python- oder Node-Laufzeitstapel direkt auf dem Player

Build- und Deployment-Richtung

• Go-Binaries sollen zentral gebaut und per Ansible verteilt werden koennen
• Konfiguration soll dateibasiert und gut templatisierbar sein
• Frontend-Artefakte sollen versioniert und reproduzierbar baubar sein

Architekturfolgen aus diesen Entscheidungen

• der Player bleibt moeglichst nah an einem Appliance-Modell
• Browserfehler duerfen nicht direkt die eigentliche Logik bestimmen
• Renderer und Systemlogik bleiben getrennt
• Serverlogik ist zentralisiert, Playerlogik minimal und robust

Bewusst vertagte Entscheidungen

• moeglicher spaeterer Wechsel auf Wayland
• exakte Frontend-Framework-Wahl
• genaue Auspraegung des Build-Systems fuer Frontend-Artefakte
• eventuelle Objekt-Storage-Einfuehrung statt einfachem Dateispeicher

Aktueller technischer Grundsatz

Wenn zwei Varianten funktional gleichwertig sind, wird die Variante mit weniger Laufzeitabhaengigkeiten, einfacherem Deployment und besserem Offline-Verhalten bevorzugt.