diff --git a/README.md b/README.md index 0c7ad1b..9054e42 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ Die Trennung von `/srv/docker/infoboard-netboot` ist sinnvoll, damit: - Technologieentscheidungen: `TECH-STACK.md` - Template-/Kampagnenkonzept: `docs/TEMPLATE-KONZEPT.md` - Provisionierungskonzept: `docs/PROVISIONIERUNGSKONZEPT.md` +- Player-Konzept: `docs/PLAYER-KONZEPT.md` +- Server-Konzept: `docs/SERVER-KONZEPT.md` ## Projektstruktur diff --git a/ansible/README.md b/ansible/README.md new file mode 100644 index 0000000..76c9abd --- /dev/null +++ b/ansible/README.md @@ -0,0 +1,8 @@ +# Ansible + +Hier liegen spaeter Rollen, Playbooks und Inventories fuer: + +- Erstinstallation neuer Screens +- Updates bestehender Screens +- Server-Deployment +- Display-spezifische Konfigurationen diff --git a/docs/PLAYER-KONZEPT.md b/docs/PLAYER-KONZEPT.md new file mode 100644 index 0000000..3a998ad --- /dev/null +++ b/docs/PLAYER-KONZEPT.md @@ -0,0 +1,299 @@ +# Info-Board Neu - Player-Konzept + +## Ziel + +Der Player ist eine moeglichst schlanke Display-Appliance fuer Raspberry Pi OS Lite. + +Er soll: + +- Bilder, Videos, PDFs und Webseiten anzeigen +- globale Kampagnen, tenantbezogene Playlists und Fallback sauber priorisieren +- bei Serverausfall autonom weiterlaufen +- per MQTT steuerbar sein +- per Ansible einfach ausrollbar sein +- moeglichst wenige Laufzeitabhaengigkeiten haben + +## Leitprinzip + +Chromium ist nur Renderer, nicht Steuerzentrale. + +Das bedeutet: + +- Chromium zeigt nur die lokale `player-ui` +- die `player-ui` entscheidet, was angezeigt wird +- der `player-agent` verwaltet Sync, Cache, Kommandos und Status +- externe URLs werden nie unkontrolliert direkt als Hauptbrowserziel verwendet + +## Komponenten + +### `player-agent` + +Implementierung: + +- bevorzugt in `Go` +- als einzelnes Binary auslieferbar + +Aufgaben: + +- Registrierung beim Server +- Abruf von Konfiguration, Playlist, Kampagne und Medienmanifest +- lokaler Mediencache +- MQTT-Kommunikation +- Heartbeat und Statusmeldungen +- Screenshot-Erzeugung +- Ausfuehrung von Admin-Kommandos +- Ueberwachung von Chromium und `player-ui` + +### `player-ui` + +Implementierung: + +- lokale Web-Anwendung +- von Chromium im Kiosk dargestellt + +Aufgaben: + +- Playlist-Logik lokal darstellen +- Prioritaet `campaign > tenant_playlist > fallback` umsetzen +- Bilder, Videos, PDFs und Webseiten anzeigen +- Lade-Timeouts und Fehlerpfade umsetzen +- Offline-/Degraded-Overlay anzeigen +- Renderer-seitige Healthchecks liefern + +### Chromium + +Aufgabe: + +- reine Darstellung der lokalen `player-ui` + +Vorgaben: + +- Kiosk-Modus +- Vollbild +- moeglichst ohne weitere Browser-Interaktion +- Neustart durch systemd/Watchdog erlaubt + +## Laufzeitmodell + +## Startreihenfolge + +1. Basis-System bootet +2. X11-Minimalstack startet +3. `player-agent` startet +4. `player-ui` ist lokal erreichbar +5. Chromium startet auf lokaler URL +6. Agent fuehrt ersten Sync und Registrierungsablauf aus + +## Lokaler Zustand + +Der Player haelt lokal vor: + +- aktuelle Konfiguration +- letzte gueltige Playlist +- letzte gueltige Kampagne +- lokales Medienmanifest +- heruntergeladene Medien +- Status-/Snapshot-Metadaten + +Empfohlene Pfade: + +- `/etc/signage/config.yml` +- `/var/lib/signage/cache/` +- `/var/lib/signage/media/` +- `/var/lib/signage/state/` +- `/var/log/signage/` + +## Inhaltsprioritaet + +Die Anzeigeentscheidung erfolgt immer in dieser Reihenfolge: + +1. aktive globale Kampagne fuer diesen Screen +2. normale tenantbezogene Playlist +3. lokaler Fallback aus dem konfigurierten Verzeichnis + +### Kampagnenmodus + +Wenn eine gueltige Kampagne fuer den Screen aktiv ist: + +- zeigt der Player nur den Kampagneninhalt +- der Firmencontent wird temporär uebersteuert +- nach Ablauf oder Deaktivierung springt der Player automatisch zurueck + +### Tenant-Playlist-Modus + +Wenn keine Kampagne aktiv ist: + +- wird die tenantbezogene Playlist ausgewertet +- nur aktive und zeitlich gueltige Elemente werden angezeigt + +### Fallback-Modus + +Wenn weder Kampagne noch gueltige Playlist-Inhalte verfuegbar sind: + +- werden alle Dateien aus dem Fallback-Verzeichnis nacheinander angezeigt + +## Medientypen + +### Bild + +- lokal oder aus Cache +- Anzeige fuer definierte Dauer + +### Video + +- lokal oder aus Cache +- entweder feste Dauer oder bis Medienende + +### PDF + +- lokal oder aus Cache +- Anzeige ueber Browser/PDF-Renderer + +### Webseite + +- live geladen oder kontrolliert zwischengespeichert +- immer mit `load_timeout` +- nie rohe Browser-Fehlerseite dauerhaft stehen lassen + +## Fehlerverhalten + +### Grundregeln + +- Fehler eines einzelnen Items duerfen den Player nicht blockieren +- jeder Fehler fuehrt zu `retry`, `skip` oder `fallback` +- haengende Browserfehlerseiten muessen aktiv verhindert werden + +### Typische Fehlerfaelle + +- Medium fehlt lokal +- externe URL nicht erreichbar +- PDF fehlerhaft +- Video unlesbar +- Webseite liefert 404/500 oder timeout + +### Reaktion + +- Fehler loggen +- Status aktualisieren +- ggf. Overlay auf `degraded` +- zum naechsten Element wechseln oder definierte Retry-Logik ausfuehren + +## Offline-Verhalten + +Offline-Betrieb ist Standardfall, nicht Sonderfall. + +Wenn der Server nicht erreichbar ist: + +- laeuft die Wiedergabe lokal weiter +- letzte gueltige Daten bleiben aktiv +- Overlay zeigt den Verbindungszustand an +- Heartbeats und Status koennen lokal zwischengespeichert oder spaeter aktualisiert werden + +## Overlay-Konzept + +Das Overlay soll klein und unaufdringlich sein. + +Zustaende: + +- `online` +- `degraded` +- `offline` + +Moegliche Anzeige: + +- kleines Symbol in Ecke +- optional Text wie `offline - letzter Sync vor 2h` + +## Orientierung und Display-Konfiguration + +Jeder Screen hat: + +- fachliche Orientierung: `portrait` oder `landscape` +- technische Rotation: `0`, `90`, `180`, `270` + +Diese Werte beeinflussen: + +- Chromium-Startkonfiguration +- X11-/Display-Setup +- Asset-Auswahl bei Kampagnen +- Darstellung in der `player-ui` + +## Watchdogs + +### Agent-Watchdog + +- systemd Restart-Strategie +- eigener Healthcheck fuer Sync und Broker-Verbindung + +### Renderer-Watchdog + +- Ueberwachung von Chromium +- Erkennung haengender Darstellungen +- geordneter Neustart bei Freeze oder Crash + +## Screenshots und Status + +Der Player erzeugt Screenshots: + +- bei Item-Wechsel +- zyklisch +- auf Admin-Anforderung + +Der Player meldet Status: + +- aktuelles Item +- Quelle (`campaign`, `tenant_playlist`, `fallback`) +- Fehlerstatus +- letzter Sync +- Heartbeat + +## MQTT-Kommandos auf dem Player + +Mindestens zu unterstuetzen: + +- `reload` +- `restart_player` +- `reboot` +- `display_on` +- `display_off` +- `refresh_snapshot` +- `clear_cache` + +## Minimaler Paketbedarf + +Auf dem Player anzustreben: + +- Raspberry Pi OS Lite +- Xorg-Minimalstack +- Chromium +- eigenes Go-Binary +- systemd + +Vermeiden: + +- LXDE/LXQt +- LightDM, wenn nicht zwingend noetig +- mehrere externe Viewer +- schwergewichtige Laufzeitstapel auf dem Geraet + +## Zielstruktur im Repo + +Empfohlene Unterstruktur fuer den Player: + +- `player/agent/` +- `player/ui/` +- `player/systemd/` +- `player/config/` +- `player/scripts/` + +## Testfaelle fuer den Player + +- lokaler Start ohne Server +- späterer Verbindungsaufbau zum Server +- Wechsel zwischen Kampagne, Playlist und Fallback +- kurzer Netzverlust +- kaputte Web-URL +- defektes PDF +- Neustart von Chromium +- Screenshot-Erzeugung +- Rotation/Portrait/Landscape diff --git a/docs/SERVER-KONZEPT.md b/docs/SERVER-KONZEPT.md new file mode 100644 index 0000000..ad57a89 --- /dev/null +++ b/docs/SERVER-KONZEPT.md @@ -0,0 +1,269 @@ +# Info-Board Neu - Server-Konzept + +## Ziel + +Der Server ist die zentrale Steuer- und Verwaltungsinstanz der Plattform. + +Er soll: + +- Benutzer, Firmen und Screens verwalten +- Medien und Playlists bereitstellen +- globale Templates und Kampagnen steuern +- Provisionierung neuer Screens ausloesen +- Status, Screenshots und Heartbeats sammeln +- MQTT und HTTPS sauber trennen + +## Grundprinzip + +Der Server ist die Quelle der fachlichen Wahrheit. + +Der Player bleibt trotzdem lauffaehig, wenn der Server temporaer nicht erreichbar ist. + +Das bedeutet: + +- Server verwaltet Konfiguration und Inhalte zentral +- Player fuehrt lokal und robust aus +- Server sendet Steuerimpulse, Player synchronisiert aktiv nach + +## Hauptkomponenten + +### Reverse Proxy + +Aufgaben: + +- TLS-Terminierung +- Routing fuer API und Web-UIs +- optionale Auth-/Header-Regeln + +### Backend-API + +Bevorzugte Sprache: + +- `Go` + +Aufgaben: + +- Authentifizierung und Autorisierung +- CRUD fuer Tenants, Users, Screens, Medien, Playlists +- Verwaltung globaler Templates und Kampagnen +- Player-Sync-Endpunkte +- Speicherung von Status und Screenshots +- Start von Provisionierungsjobs + +### Admin-UI + +Aufgaben: + +- Gesamtübersicht aller Screens +- Vorschau und Status +- Template-/Kampagnenverwaltung +- Kommandos und Provisionierung + +### Tenant-UI + +Aufgaben: + +- Uploads und Medienverwaltung pro Firma +- Pflege der monitorbezogenen Playlist +- Vorschau des eigenen Screens + +### Datenbank + +Empfehlung: + +- PostgreSQL + +Aufgaben: + +- Speicherung fachlicher Daten +- Status, Jobs, Revisionen, Zuordnungen + +### MQTT-Broker + +Empfehlung: + +- Mosquitto + +Aufgaben: + +- Heartbeats +- Statusmeldungen +- Events +- Kommandos und ACKs + +### Dateispeicher + +Aufgaben: + +- Uploads +- Screenshots +- ggf. serverseitig vorbereitete Medien + +V1: + +- Dateisystem ausreichend + +## Fachliche Bereiche + +## 1. Mandanten und Benutzer + +Der Server trennt: + +- globale Admins +- tenantgebundene Nutzer + +Regel: + +- Firmen sehen nur ihren Bereich +- Admins sehen alles + +## 2. Screen-Verwaltung + +Der Server kennt jeden Screen mit: + +- ID +- Name +- Klasse +- Orientierung +- Rotation +- Tenant-Zuordnung +- technischem Registrierungsstatus + +## 3. Medienverwaltung + +Der Server verwaltet: + +- Uploads +- externe Medienreferenzen +- Metadaten +- tenant- oder screenspezifische Zuordnung + +## 4. Playlist-Verwaltung + +Der Server verwaltet tenantbezogene Inhalte pro Screen. + +Wichtige Felder: + +- Reihenfolge +- Dauer +- `valid_from` +- `valid_until` +- Fehlerstrategie +- Cache-Politik + +## 5. Template- und Kampagnenverwaltung + +Der Server stellt den globalen Orchestrierungsbereich bereit. + +Funktionen: + +- Templates erstellen +- Szenen pflegen +- Zielgruppen waehlen +- Kampagnen aktivieren/deaktivieren +- Zeitfenster setzen +- Uebersteuerung sichtbar machen + +## 6. Provisionierung + +Der Server startet Provisionierungsjobs fuer neue Screens. + +Aufgaben: + +- Eingaben aus Admin-UI entgegennehmen +- Job anlegen +- Secret-Handling absichern +- Worker oder Jobrunner starten +- Fortschritt speichern +- Fehler sauber rueckmelden + +## API-Bereiche + +Die API soll mindestens diese Domänen haben: + +- `auth` +- `tenants` +- `users` +- `screens` +- `media` +- `playlists` +- `templates` +- `campaigns` +- `player` +- `commands` +- `provisioning` + +## Revisionsmodell + +Der Server arbeitet mit Revisionen, damit Player effizient synchronisieren koennen. + +Mindestens: + +- `config_revision` +- `playlist_revision` +- `media_revision` +- `campaign_revision` + +## Status- und Vorschaukonzept + +Der Server speichert: + +- letzten bekannten Heartbeat +- letzten Status +- letzten Screenshot +- aktuelle Inhaltsquelle pro Screen + +Die Admin-UI soll damit erkennen: + +- online/offline +- normaler tenantbezogener Betrieb +- globale Kampagnen-Uebersteuerung +- Fallback-Betrieb +- Fehlerzustand + +## Provisionierungsjobrunner + +Die Provisionierung soll nicht direkt in Web-Requests laufen. + +Stattdessen: + +- API legt Job an +- dedizierter Worker/Jobrunnner arbeitet ihn ab +- Fortschritt wird in DB gespeichert + +## Docker-Compose-Zielbild + +Sinnvolle Komponenten in `compose/`: + +- `reverse-proxy` +- `backend` +- `postgres` +- `mosquitto` +- optional `worker` + +## Sicherheitsgrundsaetze + +- Root-Bootstrap-Geheimnisse nur kurzlebig oder referenziert speichern +- API- und MQTT-Zugaenge getrennt behandeln +- alle Admin-Kommandos auditieren +- Tenant-Trennung strikt serverseitig erzwingen + +## Zielstruktur im Repo + +Empfohlene Unterstruktur fuer den Server: + +- `server/backend/` +- `server/admin-ui/` +- `server/tenant-ui/` +- `server/worker/` +- `compose/` + +## Testfaelle fuer den Server + +- Tenant sieht nur eigene Daten +- Admin sieht alle Daten +- Kampagne ueberschreibt tenantbezogenen Content korrekt +- Screen-Provisionierung legt Job sauber an +- Player-Sync ueber Revisionen funktioniert +- MQTT-Kommandos werden protokolliert +- Screenshot-Upload erscheint im Admin-Dashboard diff --git a/player/README.md b/player/README.md new file mode 100644 index 0000000..78224d8 --- /dev/null +++ b/player/README.md @@ -0,0 +1,11 @@ +# Player + +Hier liegen spaeter die Komponenten fuer den Screen-Client. + +Geplant: + +- `agent/` fuer den `player-agent` +- `ui/` fuer die lokale `player-ui` +- `systemd/` fuer Units +- `config/` fuer Beispielkonfigurationen +- `scripts/` fuer lokale Hilfsskripte diff --git a/server/README.md b/server/README.md new file mode 100644 index 0000000..cd7f928 --- /dev/null +++ b/server/README.md @@ -0,0 +1,10 @@ +# Server + +Hier liegen spaeter die zentralen Server-Komponenten. + +Geplant: + +- `backend/` fuer API und Fachlogik +- `admin-ui/` fuer die Admin-Oberflaeche +- `tenant-ui/` fuer die Firmenoberflaeche +- `worker/` fuer Provisionierungs- und Hintergrundjobs