morz-infoboard/PLAN.md

Info-Board Neu - Architekturplan

Zielbild

Das neue System ersetzt die bestehende pictur-/LXDE-basierte Loesung durch eine schlanke, zentral verwaltete Signage-Plattform.

Ziele:

• moeglichst wenig Ballast auf den Player-Clients
• Anzeige von Bildern, Videos, PDFs und Webseiten
• flexible Playlist pro Monitor
• Fallback auf sequentielle Anzeige aller Medien aus einem konfigurierten Verzeichnis
• mandantenfaehige Pflegeoberflaeche pro Monitor/Firma
• Admin-Oberflaeche fuer Gesamtsteuerung aller Monitore
• globale Admin-Templates zur monitoruebergreifenden Orchestrierung
• autonomer Offline-Betrieb bei Serverausfall
• einfache Verteilung per Ansible
• moeglichst geringe Abhaengigkeit vom Unterbau innerhalb Debian-/Raspberry-Pi-OS-Welt

Basisentscheidungen

Betriebssystem

• Player-Basis: aktuelles Raspberry Pi OS Lite auf Debian-13-Basis
• Server-Basis: Debian-artiges System, bevorzugt containerisiert
• keine volle Desktop-Umgebung auf den Playern

Display-Stack

• fuer Version 1 X11 statt Wayland
• Grund: konservativer, besser vorhersehbar fuer Chromium-Kiosk, Screenshot-Erzeugung, Watchdogs und Raspberry-spezifische Display-Steuerung
• kein LXDE, kein LightDM als Komfortschicht, nur ein minimaler X11-Kiosk-Stack

Container-Strategie

• Server: Docker Compose ist sinnvoll und empfohlen
• Player: kein Voll-Docker-Ansatz fuer den Grafikpfad in Version 1
• Player besser als native Dienste mit systemd + Chromium-Kiosk

Sprach- und Laufzeitstrategie

• Go ist die bevorzugte Sprache fuer systemnahe und portable Komponenten
• insbesondere gilt das fuer den player-agent und nach Moeglichkeit auch fuer zentrale Backend-Komponenten
• Ziel ist eine geringe Zahl externer Laufzeitabhaengigkeiten und moeglichst einfache Verteilung per Ansible
• fuer Browser-Oberflaechen bleibt JavaScript/TypeScript im Frontend natuerlich zulaessig
• falls einzelne Server-Bausteine spaeter aus pragmatischen Gruenden anders umgesetzt werden, soll das begruendet und dokumentiert werden

Gesamtarchitektur

Das System besteht aus zwei Hauptteilen:

1. zentraler Server fuer Verwaltung, API, Medien, Rechte und Steuerung
2. schlanke Player-Clients auf den Monitoren

Server-Komponenten

• Reverse Proxy
• Backend API
• Admin-Oberflaeche
• mandantenbezogene Management-Oberflaeche
• PostgreSQL
• MQTT-Broker
• Dateispeicher fuer Uploads, Vorschaubilder und Screenshots

Player-Komponenten

• player-agent als nativer systemd-Dienst
• player-ui als lokale Web-Anwendung
• Chromium im Kiosk-Modus, der nur die lokale player-ui rendert
• lokaler Cache fuer Playlist, Medien und Status

Rollenmodell

Monitor-/Firmen-Oberflaeche

Jede Firma sieht nur den ihr zugeordneten Monitor bzw. Kanal.

Funktionen:

• Medien hochladen
• Medien loeschen und ordnen
• Playlist pflegen
• Anzeigedauer je Eintrag festlegen
• valid_from und valid_until setzen
• lokale Vorschau des eigenen Monitors sehen

Admin-Oberflaeche

Die Administration der Schule sieht und steuert die gesamte Anlage.

Funktionen:

• Inhalte aller Monitore verwalten
• Monitore global uebersichtlich sehen
• Vorschau/Screenshots aller Monitore sehen
• Reload des Players ausloesen
• Seite neu laden
• Dienste neu starten
• Monitore rebooten
• Monitore an- und ausschalten
• globale Templates erstellen, testen und aktivieren
• temporaere Kampagnen fuer mehrere oder alle Monitore einschalten und wieder abschalten
• neue Monitore initial provisionieren und betriebsbereit ausrollen

Globale Template-Orchestrierung

Die Admin-Seite bekommt zusaetzlich einen globalen Orchestrierungsbereich.

Ziele:

• grossformatige monitoruebergreifende Botschaften wie SCHOENE FERIEN oder MORZ-INFO
• saisonale oder veranstaltungsbezogene globale Motive, z. B. Weihnachten
• schnelles temporäres Ueberstimmen des Firmencontents
• Rueckkehr zum normalen Firmencontent auf Knopfdruck

Grundprinzip:

• globale Templates sind administrative Kampagnen mit hoeherer Prioritaet als tenantbezogene Inhalte
• sie koennen auf einzelne Monitore, Monitorgruppen oder alle Monitore angewendet werden
• sie sind zeitlich planbar oder manuell aktivierbar
• nach Deaktivierung faellt der Bildschirm automatisch auf seine normale tenantbezogene Playlist zurueck

Automatische Screen-Provisionierung

Die Admin-Oberflaeche soll neue Bildschirme nicht nur fachlich anlegen, sondern technisch in Betrieb nehmen koennen.

Zielablauf:

• Admin gibt display_id, Ziel-IP und initiale Root-Zugangsdaten an
• das System stellt per SSH eine Erstverbindung her
• ein Deploy-Key oder dedizierter Verwaltungsschluessel wird hinterlegt
• noetige Pakete und Komponenten werden installiert
• Konfiguration fuer den neuen Screen wird ausgerollt
• der Player wird gestartet und meldet sich selbststaendig am Server an

Der Vorgang soll moeglichst als gefuehrter Provisionierungs-Workflow im Admin-Backend verfuegbar sein.

Wichtige Randbedingungen:

• Root-Passwoerter duerfen nicht dauerhaft im Klartext gespeichert werden
• Provisionierungsdaten sind nur fuer Admins sichtbar
• jeder Provisionierungslauf muss nachvollziehbar protokolliert werden
• die eigentliche Ausbringung soll auf einem automatisierbaren Ansible- oder SSH-Workflow basieren, nicht auf ad-hoc-Shellmagie im Browser

Datenmodell

Zentrale Entitaeten

• tenant
• screen
• user
• media_asset
• playlist
• playlist_item
• display_template
• template_scene
• template_assignment
• campaign
• screen_status
• screen_snapshot
• device_command
• sync_state

Wichtige Felder

screen

• id
• name
• tenant_id
• location
• rotation
• resolution
• enabled

media_asset

• id
• tenant_id
• type (image, video, pdf, web)
• source_kind (upload, remote_url)
• storage_path
• original_url
• checksum
• mime_type
• created_at

playlist_item

• id
• playlist_id
• screen_id
• order_index
• type
• src
• duration
• valid_from
• valid_until
• load_timeout
• cache_policy
• on_error
• enabled

screen_status

• screen_id
• online
• last_heartbeat
• current_item
• current_type
• current_since
• last_sync_at
• server_connected
• cache_state
• error_state

screen_snapshot

• screen_id
• captured_at
• image_path

Playlist-Konzept

Unterstuetzte Typen

• Bild
• Video
• PDF
• Webseite
• Verzeichnisreferenz als Fallback-/Sammelquelle

Pro Eintrag steuerbar

• Dauer
• Gueltigkeit ueber valid_from und valid_until
• Reihenfolge
• Timeout fuer das Laden
• Cache-Strategie
• Fehlerverhalten (skip, retry, fallback)

Fallback-Regel

Wenn keine aktive Playlist vorhanden ist oder kein gueltiges Item aktiv ist, zeigt der Player alle Medien aus einem konfigurierten Fallback-Verzeichnis nacheinander an.

Eigenschaften:

• deterministische Reihenfolge, standardmaessig alphabetisch
• medientypgerechte Anzeigezeiten
• funktioniert komplett lokal aus dem Cache oder Dateisystem

Prioritaetsregel fuer globale Templates

Die Inhaltsauswahl pro Screen folgt in v1 einer klaren Prioritaetskette:

1. aktive globale Kampagne bzw. aktives Admin-Template
2. normale tenantbezogene Playlist des Monitors
3. lokaler Fallback aus dem konfigurierten Verzeichnis

Das verhindert spaeteres Anflanschen und macht die Uebersteuerung von Beginn an explizit.

Wichtige Regeln:

• globale Templates sind immer explizit aktiv oder inaktiv
• sie koennen valid_from und valid_until besitzen
• sie koennen manuell sofort deaktiviert werden
• nach Ablauf oder Deaktivierung setzt der Screen automatisch beim normalen Inhalt fort

Offline- und Cache-Strategie

Offline-Betrieb ist Pflicht.

Der Player speichert lokal:

• die letzte gueltige Playlist
• alle noetigen Medien
• letzten bekannten Status
• letzte Server-/Sync-Metadaten

Bei Serverausfall:

• Wiedergabe laeuft lokal weiter
• ein kleines Overlay-Symbol zeigt den Offline-Zustand an
• Heartbeat wird lokal gepuffert oder beim Wiederverbinden aktualisiert

Overlay-Zustaende

• gruen: online
• gelb: Verbindung instabil oder Daten veraltet
• rot: keine Verbindung zum Server

Vermeidung von Chromium-Haengern

Chromium rendert niemals direkt externe Medien- oder Playlist-URLs.

Stattdessen:

• Chromium zeigt nur http://127.0.0.1:<port>/player
• die lokale player-ui kapselt alle Medien und Fehlerzustande
• externe Medien werden vorher geladen oder lokal gespiegelt, wo immer moeglich

Konsequenzen:

• keine haengenden 404-Fehlerseiten als Hauptansicht
• Timeouts pro Inhalt moeglich
• bei Fehlern: Skip oder Fallback statt Stehenbleiben
• lokaler Watchdog kann Anzeige und Browser neu initialisieren

Vorschaukonzept

Eine Vorschau ist sinnvoll, aber nicht als permanenter Livestream.

Empfohlene Umsetzung:

• Screenshot bei Item-Wechsel
• zusaetzlicher Screenshot in Intervallen, z. B. alle 30 bis 60 Sekunden
• Anzeige des letzten Screenshots in Admin- und Firmen-Oberflaeche
• ergaenzt durch strukturierte Statusdaten

Die Vorschau soll auch sichtbar machen, ob ein Screen gerade:

• tenantbezogenen Normalbetrieb zeigt
• von einer globalen Kampagne uebersteuert wird
• im Fallback-Modus laeuft

Statusdaten:

• aktuelles Item
• Typ
• Startzeit
• Restlaufzeit
• letzter Heartbeat
• letzter Sync
• Fehlerstatus

Kommunikation

HTTPS

Fuer:

• Login
• Uploads
• API-Aufrufe
• Playlist-Bearbeitung
• Download von Medien und Konfiguration
• Abruf von Screenshots und Status

MQTT

Fuer:

• Heartbeat
• Statusmeldungen
• Kommandos
• Acknowledgements
• Hinweis auf Playlist-Aenderungen

MQTT-Topics

• signage/screen/<screen-id>/heartbeat
• signage/screen/<screen-id>/status
• signage/screen/<screen-id>/event
• signage/screen/<screen-id>/command
• signage/screen/<screen-id>/ack

Befehle

• reload
• restart_player
• reboot
• display_on
• display_off
• refresh_snapshot
• clear_cache

Player-Aufbau

player-agent

Aufgaben:

• Registrierung des Geraets
• HTTPS-Sync
• MQTT-Kommunikation
• Cache-Verwaltung
• Befehlsausfuehrung
• Screenshot-Erzeugung
• Ueberwachung lokaler Dienste

Technische Vorgabe:

• Implementierung bevorzugt in Go
• Auslieferung moeglichst als einzelnes Binary

player-ui

Aufgaben:

• lokale Wiedergabeoberflaeche
• Darstellung von Bild, Video, PDF und Web
• Auswertung von Zeitfenstern
• Umschalten zwischen Playlist und Fallback
• Offline-/Fehler-Overlay

Server-Aufbau

Kernkomponenten

• API-Backend
• Admin-Frontend
• Tenant-Frontend
• MQTT-Broker
• Datenbank
• Media-Storage

Zusaetzliche fachliche Server-Faehigkeiten:

• Verwaltung globaler Templates
• Konfiguration monitoruebergreifender Layouts und Szenen
• Aktivierung, Deaktivierung und Zeitplanung globaler Kampagnen
• technische Provisionierung neuer Screens ueber einen gefuehrten Admin-Workflow

Technische Vorgabe:

• Backend bevorzugt in Go, sofern die Entwicklungsdynamik nicht klar dagegen spricht
• Frontends als Web-Anwendungen mit ueblichem Browser-Stack

Betriebsform

• bevorzugt per Docker Compose
• klare Trennung von persistenten Daten, Konfiguration und Deploy-Code

Minimale Abhaengigkeiten auf dem Player

Das Ziel ist ein moeglichst kleiner Satz an Laufzeitabhaengigkeiten.

Bevorzugt:

• Raspberry Pi OS Lite
• Xorg-Minimalstack
• Chromium
• ein eigenes Player-Binary in Go oder eine gleichwertig schlanke Laufzeit
• systemd

Vermeiden:

• voller Desktop
• mehrere externe Viewer wie feh, vlc, wmctrl, xdg-open
• Python-/Node-Laufzeiten mit grossem Paketbaum direkt auf dem Client, wenn vermeidbar

Ansible-Zielstruktur

Rollen

• signage_base
• signage_player
• signage_display
• signage_server
• signage_provision

Provisionierungsmodell

Die Erstinstallation eines neuen Screens soll auf Ansible aufsetzen.

Vorgesehener Ablauf:

1. Screen im Admin-Backend anlegen
2. einmalige technische Zugangsdaten fuer die Erstverbindung angeben
3. Backend startet einen Provisionierungsjob
4. der Job nutzt SSH/Ansible fuer Basis-Setup, Key-Deployment, Paketinstallation und Konfiguration
5. nach erfolgreicher Provisionierung verwendet der Screen nur noch den hinterlegten Verwaltungsschluessel und seine technische Geraeteidentitaet

Damit wird die GUI zur komfortablen Steuerschicht ueber einem reproduzierbaren Automatisierungsprozess.

Konfigurationspfade auf dem Client

• /etc/signage/config.yml
• /var/lib/signage/cache/
• /var/lib/signage/media/
• /var/lib/signage/state/
• /var/log/signage/

Migrationsstrategie

1. Architektur finalisieren
2. Datenmodell finalisieren
3. Minimalen Player-Prototyp bauen
4. Server-Minimalversion bauen
5. Referenz-Raspi aufsetzen
6. Offline-/Netzfehler-/Timeout-Szenarien testen
7. Management-Oberflaechen ausbauen
8. Ansible-Rollen erstellen
9. Einen Pilotmonitor migrieren
10. Restliche Monitore sukzessive migrieren

Parallel von Anfang an mitdenken:

• globale Template-Orchestrierung darf kein Nachbau sein, sondern muss im Inhalts- und Prioritaetsmodell direkt vorgesehen werden

Teststrategie

Zu testen sind mindestens:

• kurzer Netzverlust
• kompletter Serverausfall
• MQTT-Ausfall bei funktionierendem HTTPS
• HTTPS-Ausfall bei funktionierendem MQTT
• kaputte URL in Playlist
• defekte PDF-Datei
• grosses Video
• Wechsel von valid_from/valid_until waehrend des laufenden Betriebs
• Reload aus der Admin-Oberflaeche
• Dienstneustart aus der Admin-Oberflaeche
• Reboot aus der Admin-Oberflaeche
• Display an/aus
• Screenshot-Erzeugung unter Last

Projektstruktur-Empfehlung

Ein separates Projektverzeichnis ist sinnvoll, um die neue Architektur sauber von der bestehenden Netboot-Struktur zu trennen.

Empfohlener Pfad:

• /srv/docker/info-board-neu

Dieses Verzeichnis sollte mindestens enthalten:

• PLAN.md
• TODO.md
• spaeter compose/, ansible/, server/, player/, docs/