morz-infoboard/docs/PROVISIONIERUNGSKONZEPT.md

Info-Board Neu - Provisionierungskonzept

Ziel

Neue Displays sollen aus dem Admin-Backend heraus technisch in Betrieb genommen werden koennen.

Der Workflow soll mindestens leisten:

• neuen Screen fachlich anlegen
• initiale Verbindung per IP und Bootstrap-Zugang herstellen
• SSH-Key fuer dauerhafte Verwaltung hinterlegen
• noetige Komponenten installieren
• Screen-spezifische Konfiguration ausrollen
• Display in lauffaehigen Zustand versetzen

Das Konzept ist ausdruecklich nicht auf 9 Monitore begrenzt. Es muss auch kuenftige Einzelanzeigen wie Vertretungsplan-Displays sauber abbilden.

Grundprinzip

Die Admin-Oberflaeche ist der Einstiegspunkt, aber die eigentliche Ausbringung erfolgt reproduzierbar ueber einen serverseitigen Provisionierungsjob.

Technische Leitlinie:

• GUI sammelt Eingaben und zeigt Fortschritt
• Backend erzeugt Provisionierungsjob
• Jobrunner fuehrt SSH-/Ansible-Schritte aus
• Ergebnis wird protokolliert und in der UI sichtbar gemacht

Eingaben fuer einen neuen Screen

Mindestens erforderlich:

• display_id bzw. screen_slug
• Anzeigename
• Ziel-IP-Adresse
• Bootstrap-Benutzer, Default root
• Bootstrap-Passwort oder alternativer Initial-Key
• gewuenschte Orientierung
• optionale Rotation
• Screen-Klasse oder Geraetetyp
• Tenant-Zuordnung, falls direkt bekannt

Optional sinnvoll:

• Aufloesung
• Fallback-Verzeichnis
• Snapshot-Intervall
• Zugehoerigkeit zu Gruppen
• Standortbeschreibung

Orientierung und Rotationsmodell

Die Ausrichtung ist von Anfang an ein Pflichtfeld.

Fachliche Orientierung

• portrait
• landscape

Technische Rotation

• 0
• 90
• 180
• 270

Grundregel:

• die Orientierung ist die fachliche Voreinstellung fuer Templates und Layouts
• die Rotation ist die technische Ableitung fuer den Display-Stack auf dem Geraet

Beispiele:

• Infowand-Displays: typischerweise portrait
• Vertretungsplan-Displays: typischerweise landscape

Diese Werte muessen in Provisionierung, Player-Konfiguration und Kampagnenlogik gleichermassen sichtbar sein.

Screen-Klassen

Um skalierbar zu bleiben, sollte die Provisionierung mit Klassen oder Profilen arbeiten.

Empfohlene Startklassen:

• info_wall_display
• single_info_display
• vertretungsplan_display

Diese Klassen koennen Defaults liefern fuer:

• Orientierung
• Rotation
• Aufloesung
• Gruppenmitgliedschaften
• Fallback-Verzeichnis
• spezielle UI- oder Template-Voreinstellungen

Provisionierungsablauf

1. Fachliches Anlegen

Im Admin-Backend wird der Screen angelegt mit:

• Name
• ID
• Klasse
• Orientierung
• Tenant-Zuordnung
• Standort

2. Start des Provisionierungsjobs

Der Admin gibt die technischen Zugangsdaten fuer die Erstverbindung an.

Wichtig:

• Passwort nur fuer den aktuellen Job verwenden
• keine dauerhafte Klartextspeicherung

3. Verbindungsaufbau

Der Jobrunner versucht per SSH die Verbindung herzustellen.

Pruefpunkte:

• Erreichbarkeit
• SSH-Port
• gueltige Zugangsdaten
• Architektur und Betriebssystem grob erkennen

4. Bootstrap

Auf dem Zielsystem werden vorbereitet:

• Verwaltungsschluessel installieren
• optional dedizierten Verwaltungsbenutzer anlegen
• Basisverzeichnisse anlegen
• Systemvoraussetzungen pruefen

5. Basisinstallation

Installiert werden mindestens:

• noetige Systempakete
• X11-Minimalstack
• Chromium
• Player-Agent
• Player-UI oder deren Artefakte
• systemd-Units

6. Screen-Konfiguration

Ausgerollt werden mindestens:

• screen_id
• Server-URL
• MQTT-Parameter
• Orientierung und Rotation
• Snapshot-Intervall
• Fallback-Verzeichnis
• Gruppen oder Zielprofile

7. Verifikation

Der Job prueft mindestens:

• Dienste laufen
• lokaler Player-Endpunkt ist erreichbar
• Agent registriert sich am Server
• Heartbeat kommt an
• Screenshot oder Statusmeldung funktioniert

8. Abschluss

Der Provisionierungsjob wird als erfolgreich markiert und der Screen ist regulär verwaltbar.

Sicherheitsmodell

Bootstrap-Geheimnisse

Regeln:

• Root-Passwoerter nicht dauerhaft im Klartext speichern
• wenn Speicherung noetig ist, nur kurzlebig und stark geschuetzt
• besser: nur Referenz auf temporären Secret-Speicher

Verwaltung nach Erstinstallation

Nach erfolgreicher Provisionierung gilt:

• weitere Verwaltung nur noch per SSH-Key
• der Screen besitzt eine technische Geraeteidentitaet
• API- und MQTT-Zugangsdaten sind geraetebezogen

Protokollierung

Jeder Provisionierungslauf muss auditierbar sein.

Mindestens sichtbar:

• wer den Job gestartet hat
• wann er gestartet wurde
• fuer welchen Screen
• gegen welche Ziel-IP
• welche Stage aktiv war
• ob Fehler auftraten

Skalierung ueber die bestehende Wand hinaus

Das Modell muss von Anfang an mit mehreren Geraetetypen umgehen koennen.

Heute

• 9 Displays in der Infowand, Hochformat

Perspektivisch

• mindestens 4 zusaetzliche Vertretungsplan-Anzeigen, Querformat
• eventuell weitere Einzelanzeigen

Konsequenz:

• Provisionierung darf nicht implizit von einer 3x3-Wand ausgehen
• Gruppen, Klassen, Orientierung und technische Defaults muessen explizit modelliert werden

Ansible-Rolle signage_provision

Die Provisionierung sollte auf einer eigenen Rolle oder einem eigenen Playbook aufbauen.

Sinnvolle Teilbereiche:

• bootstrap
• base
• display
• player
• verify

Damit bleibt die Erstinstallation klar getrennt von spaeteren Updates.

Fehlerfaelle

Der Jobrunner soll Fehler moeglichst frueh und verstaendlich melden.

Typische Fehlerfaelle:

• Host nicht erreichbar
• falsches Passwort
• SSH blockiert
• unpassendes Betriebssystem
• Paketinstallation fehlgeschlagen
• Chromium oder X11 startet nicht
• Player-Agent registriert sich nicht

Zu jedem Fehler soll sichtbar sein:

• Stage
• kurzer Fehlertext
• ob Retry sinnvoll ist

Zielbild im Admin-Backend

Die UI fuer neue Screens sollte mindestens enthalten:

• Screen anlegen
• Klasse waehlen
• Orientierung waehlen
• Rotation festlegen oder automatisch vorbelegen
• Tenant zuordnen
• IP und Bootstrap-Zugang angeben
• Provisionierungsjob starten
• Fortschritt live oder halb-live sehen
• Erfolg/Fehler mit Details sehen

Spaetere Erweiterungen

Moegliche Ausbaustufen:

• Provisionierung ohne Passwort nur mit Bootstrap-Key
• Zero-touch-Registrierung ueber vorbereitete Images
• automatische Gruppenzuordnung nach Klasse
• Massenprovisionierung mehrerer Screens
• Neu-Provisionierung oder Rebuild eines bestehenden Screens

Fazit

Provisionierung ist nicht nur Deployment, sondern ein eigener fachlicher Workflow.

Wesentliche Grundpfeiler sind:

• Admin-gesteuerter Start
• Ansible-/SSH-basierte reproduzierbare Ausbringung
• explizite Orientierung und Rotation pro Screen
• Unterstuetzung fuer Wand-Screens und Einzelanzeigen
• sichere Umstellung von Bootstrap-Zugang auf dauerhafte schluesselbasierte Verwaltung