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

Verbindliche Betriebsannahme:

- der Provisionierungs-Worker muss das Zielgeraet per SSH erreichen koennen
- falls die Player in getrennten Netzen stehen, ist ein Jumphost- oder Routing-Konzept erforderlich
- die Provisionierung wird so gebaut, dass ein separater Worker oder Jumphost unterstuetzt wird

## 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

Verbindliche v1-Loesung:

- separate kurzlebige Secret-Verwaltung
- verschluesselte Speicherung mit App-Key
- automatische Loeschung nach Jobabschluss oder TTL-Ablauf

### 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

## Verbindliche Vorgabe fuer den Betrieb

Vor der produktiven Einfuehrung ist umzusetzen oder zu klaeren:

- ob der Server selbst in allen relevanten Player-Netzen steht
- ob ein dedizierter Provisionierungs-Worker in einem passenden Netz benoetigt wird
- ob spaeter mehrere Standorte oder VLANs zu erwarten sind

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