Diese Anleitung beschreibt, wie ein Standort ansehBAR mit seiner eigenen Infrastruktur in Betrieb nimmt. Das Repository enthält bewusst keine Angaben zu einer konkreten Einrichtung: Streaming-Server, Rekorder, Räume, Anmeldedienst und Domain bringt jeder Standort selbst mit.
Für die lokale Entwicklung reicht docker compose up -d (siehe
README). Diese Anleitung behandelt den
Produktivbetrieb.
| Baustein | Wozu | Wo konfiguriert |
|---|---|---|
| Server mit Docker und Docker Compose | Betrieb von App, Monitor, Datenbank und Reverse Proxy | – |
| Domain mit DNS-Eintrag auf den Server, Ports 80/443 | Erreichbarkeit und TLS | .env, Caddyfile |
| OIDC-Anbieter (z. B. Keycloak) mit einer Gruppe | Anmeldung und Zugangsberechtigung | .env, beim Anbieter |
| HLS-Streaming-Server | Live-Streams der Rekorder | Standortkonfiguration |
| Liste der Rekorder | Welche Streams überwacht werden | Standortkonfiguration |
Dabei gibt es drei Orte für Einstellungen:
.envauf dem Server: Secrets, Domain, OIDC, Zugang. Nicht eingecheckt.- Standortkonfiguration (
site.local.json): Stream-URL-Vorlage und Rekorderliste. Nicht eingecheckt, wird einmalig oder bei Änderungen in die Datenbank geladen. - Verwaltung im Frontend: laufende Pflege von Rekordern, Einladungen und Monitor-Einstellungen. Liegt in der Datenbank.
ansehBAR bindet jeden Rekorder über eine URL-Vorlage ein, in die der Stream-Name eingesetzt wird, z. B.
https://streaming.example.org/live/{stream}/playlist.m3u8
Der Streaming-Server muss Folgendes erfüllen:
- HLS: Unter der URL liegt eine HLS-Playlist, entweder eine Master-Playlist mit Varianten oder direkt eine Media-Playlist.
- Media-Sequence: Die Media-Playlist enthält
#EXT-X-MEDIA-SEQUENCE, und die Zahl steigt, solange der Stream läuft. Daran erkennt der Monitor, dass ein Stream wirklich live ist und nicht nur eine eingefrorene Playlist ausliefert. - Offline = 404: Sendet ein Rekorder nicht, antwortet der Server mit HTTP 404 (oder 410).
- HTTPS: Die Vorlage muss mit
https://beginnen. Weiterleitungen von HTTPS auf HTTP werden nicht befolgt. - CORS: Der Browser lädt die Streams direkt vom Streaming-Server, nicht
über ansehBAR. Der Server muss deshalb CORS-Header senden, mindestens
Access-Control-Allow-Originmit der ansehBAR-Domain oder*. - Erreichbarkeit: Der Server muss vom ansehBAR-Server aus erreichbar sein (Monitor) und von den Geräten der Nutzenden (Browser).
Schnelltest von der Kommandozeile, während ein Rekorder sendet:
# Antwortet mit 200 und Playlist? Steht ein CORS-Header in der Antwort?
curl -si -H "Origin: https://ansehbar.example.org" \
https://streaming.example.org/live/<stream>/playlist.m3u8 | head -20Danach die Chunklist aus der Antwort zweimal im Abstand von einigen
Sekunden abrufen: #EXT-X-MEDIA-SEQUENCE muss sich erhöhen.
ansehBAR meldet Nutzende über OpenID Connect an und schreibt nie etwas beim Anbieter. Am Beispiel Keycloak:
- Client anlegen: Client-ID z. B.
ansehbar, Typ confidential (Client-Authentifizierung an), Standard-Flow (Authorization Code) an. - URLs eintragen (mit
<host>= eure ansehBAR-Domain):- Valid Redirect URI:
https://<host>/oidc/callback/ - Valid Post Logout Redirect URI:
https://<host>/ - Web Origin:
https://<host> - Back-Channel Logout URL:
https://<host>/oidc/backchannel-logout/(Abmelden in Keycloak beendet dann auch die ansehBAR-Sitzung)
- Valid Redirect URI:
- Gruppe anlegen, z. B.
ansehbar-users, und die berechtigten Personen aufnehmen. - Gruppen-Claim mitschicken: einen Mapper vom Typ Group Membership
mit Claim-Name
groupsanlegen. „Full group path“ aus, damit der Gruppenname ohne führenden/ankommt. Der Mapper muss für den Userinfo-Endpunkt aktiv sein, denn ansehBAR liest die Claims von dort. - Client-Secret kopieren, es kommt in die
.env.
Andere OIDC-Anbieter funktionieren genauso, solange sie einen
Gruppen-Claim liefern. Weichen die Claim-Namen ab, lassen sie sich in der
.env umstellen (OIDC_GROUPS_CLAIM, OIDC_CLAIM_USERNAME usw.).
Zugang hat, wer mindestens eine dieser Bedingungen erfüllt:
- Mitglied der Gruppe aus
ANSEHBAR_ACCESS_GROUPist (Standardansehbar-users); - in
ANSEHBAR_BOOTSTRAP_USERSsteht (Benutzername oder E-Mail, kommagetrennt), gedacht für die erste Einrichtung und als Notzugang; - in ansehBAR unter „Verwaltung → Einladungen“ eingeladen wurde.
Alle mit Zugang haben dieselben Rechte. Wer sich anmeldet, aber keinen Zugang
hat, sieht die Seite „Kein Zugang“ mit dem Kontakt aus
ANSEHBAR_ACCESS_CONTACT.
Gruppenmitgliedschaften werden beim Login übernommen. Wird jemand aus der Gruppe entfernt, gilt das ab der nächsten Anmeldung. Für ein sofortiges Ende die Person beim OIDC-Anbieter abmelden; der Back-Channel-Logout beendet dann auch die ansehBAR-Sitzung. Entfernte Einladungen wirken sofort.
Wie der Server Schritt für Schritt eingerichtet wird (Docker, Firewall, SELinux, HTTPS, Start, Sicherung, Updates), beschreibt die Installationsanleitung. Hier stehen nur die Einstellungen, die ansehBAR betreffen.
Pflichtangaben (ohne sie startet docker compose nicht):
| Variable | Inhalt |
|---|---|
PUBLIC_BASE_URL |
Öffentliche Adresse, z. B. https://ansehbar.example.org (ohne / am Ende) |
ACME_EMAIL |
Kontaktadresse für Let's Encrypt (Hinweise zum Ablauf des Zertifikats) |
DJANGO_SECRET_KEY |
Langer Zufallswert, z. B. aus openssl rand -base64 48 |
DJANGO_ALLOWED_HOSTS |
Domain, z. B. ansehbar.example.org |
CSRF_TRUSTED_ORIGINS |
https:// + Domain |
POSTGRES_PASSWORD |
Starkes Datenbankpasswort |
OIDC_RP_CLIENT_ID |
Client-ID aus Schritt 2 |
OIDC_RP_CLIENT_SECRET |
Client-Secret aus Schritt 2 |
OIDC_OP_ISSUER |
Issuer-URL, bei Keycloak https://<keycloak>/realms/<realm>; die Endpunkte werden daraus automatisch ermittelt |
ansehBAR-spezifisch:
| Variable | Bedeutung | Standard |
|---|---|---|
ANSEHBAR_ACCESS_GROUP |
Gruppe mit Zugang | ansehbar-users |
ANSEHBAR_BOOTSTRAP_USERS |
Benutzernamen/E-Mails mit Zugang ohne Gruppe | leer |
ANSEHBAR_ACCESS_CONTACT |
Kontakt auf der Seite „Kein Zugang“ | leer |
MONITOR_INTERVAL_SECONDS |
Sekunden zwischen zwei Prüfläufen | 10 |
AUDIO_MONITOR_ENABLED |
1 = Pegelmessung (Ton) an, 0 = aus |
1 |
AUDIO_MAX_PARALLEL |
Gleichzeitige Messungen | 4 |
AUDIO_SAMPLE_SECONDS |
Länge eines Messfensters in Sekunden | 10 |
AUDIO_INTERVAL_SECONDS |
Mindestabstand zwischen den Starts zweier Durchläufe | 30 |
ANSEHBAR_SITE_CONFIG |
Pfad der Standortkonfiguration im Container | /app/site.local.json |
Die übrigen Variablen in .env.prod.example (KI-Funktionen,
LibreTranslate, Django-Admin-Gruppe) sind optional und für ansehBAR derzeit
nicht nötig.
Am Caddyfile ist nichts anzupassen: Domain (PUBLIC_BASE_URL) und
Let's-Encrypt-Kontakt (ACME_EMAIL) kommen aus der .env. Eigene
Zertifikate der Einrichtung bindet die
Installationsanleitung, Abschnitt 8 ein.
Es starten vier Container: db (PostgreSQL), app (Web und API, migriert
die Datenbank beim Start), monitor (prüft die Streams) und caddy
(HTTPS); siehe Installationsanleitung, Schritt 10.
Die Standortkonfiguration ist eine JSON-Datei mit der Stream-URL-Vorlage und
der Rekorderliste. Vorlage: backend/site.example.json.
{
"stream_url_template": "https://streaming.example.org/live/{stream}/playlist.m3u8",
"recorders": [
{"stream_name": "rec-10-r01", "room_name": "10/R01"},
{"stream_name": "rec-20-hall", "room_name": "20/R06 (Hall)", "active": false}
]
}| Feld | Pflicht | Bedeutung |
|---|---|---|
stream_url_template |
nein | URL-Vorlage mit genau einem {stream}, muss mit https:// beginnen |
recorders[].stream_name |
ja | Name des Streams auf dem Streaming-Server, eindeutig und case-sensitiv. Erlaubt sind Buchstaben, Ziffern, ., _ und -; das erste Zeichen muss ein Buchstabe oder eine Ziffer sein |
recorders[].room_name |
ja | Anzeigename, so wie die Leute den Raum nennen |
recorders[].active |
nein | false legt den Rekorder deaktiviert an; Standard true |
Die Datei als site.local.json anlegen. Dateien mit der Endung
.local.json ignoriert Git, sie landen also nicht versehentlich im
Repository. Dann laden, im Produktivbetrieb über die Standardeingabe, damit
keine zusätzliche Datei in den Container gemountet werden muss:
# Erst prüfen, was sich ändern würde:
docker compose -f docker-compose.prod.yml exec -T app \
python manage.py load_site_config --path - --dry-run < site.local.json
# Dann übernehmen:
docker compose -f docker-compose.prod.yml exec -T app \
python manage.py load_site_config --path - < site.local.jsonIn der Entwicklung liegt die Datei unter backend/site.local.json und wird
ohne weitere Angaben gefunden:
docker compose exec backend python manage.py load_site_configSo verhält sich das Laden:
- Erst prüfen, dann schreiben: Die ganze Datei wird geprüft, bevor etwas geschrieben wird. Bei Fehlern listet der Befehl alle Probleme auf und ändert nichts.
- Abgleich über den Stream-Namen: Rekorder werden anhand des Stream-Namens angelegt oder aktualisiert (Raumname, Aktiv-Status). Gelöscht wird nie etwas.
--deactivate-missing: deaktiviert zusätzlich alle Rekorder, die nicht in der Datei stehen.- Wiederholbar: Mehrfaches Laden ist unschädlich; unveränderte Einträge werden als „unverändert“ gemeldet.
- Vorrang der Datei: Ein erneutes Laden überschreibt Raumname und Aktiv-Status der aufgeführten Rekorder sowie die URL-Vorlage, auch wenn sie zwischenzeitlich in der Verwaltung geändert wurden. Wer dauerhaft mit der Datei arbeitet, pflegt Änderungen am besten dort.
Ohne Standortkonfiguration startet ansehBAR mit leerer Rekorderliste und der Beispiel-URL. Rekorder lassen sich dann auch direkt in der Verwaltung anlegen.
Mit Opencast kennt ansehBAR die geplanten Aufzeichnungen und kann zwischen
„kein Stream, weil nichts geplant ist“ und „Stream fehlt“ unterscheiden.
ansehBAR liest nur (External API, nur GET) und schreibt nie nach
Opencast. Ohne OPENCAST_URL bleibt die Anbindung aus, alles andere
funktioniert wie zuvor.
| Variable | Bedeutung | Standard |
|---|---|---|
OPENCAST_URL |
Basisadresse von Opencast, z. B. https://opencast.example.org; leer = aus. Nur https://: bei http:// (außer mit DJANGO_DEBUG=1) gleicht der Monitor nicht ab und meldet einen ERROR im Log, damit die Zugangsdaten nie unverschlüsselt übertragen werden |
leer |
OPENCAST_USER |
Benutzer für die External API | leer |
OPENCAST_PASSWORD |
Passwort dieses Benutzers. Docker Compose wertet $ in .env-Werten aus: ein $ im Passwort als $$ schreiben |
leer |
OPENCAST_SYNC_SECONDS |
Sekunden zwischen zwei Abgleichen (der Monitor gleicht in einem eigenen Thread ab; ein langsames Opencast verzögert die Stream-Prüfung nicht) | 60 |
OPENCAST_LOOKAHEAD_DAYS |
Wie viele Tage Terminplan im Voraus gelesen werden | 7 |
OPENCAST_LOOKBACK_DAYS |
Wie viele Tage zurück nach der letzten Aufzeichnung eines Raums gesucht wird (Hinweis „Letzte Aufzeichnung hatte Probleme“, siehe unten) | 7 |
Hinweis „Letzte Aufzeichnung hatte Probleme“: Er bezieht sich immer auf den
zuletzt beendeten Termin des Raums innerhalb von OPENCAST_LOOKBACK_DAYS und
verschwindet nach der nächsten sauberen Aufzeichnung. Er erscheint als gelber
Kasten in der Raumansicht, in Kachel, Smartphone-Liste und Pillen als kompakte
Zeile bzw. ⚠-Marker. Quellen und Meldungen:
- ansehBARs eigener Monitor: „Stream fehlte HH:MM–HH:MM (N min)“, nur während eines Termins und nach der Karenzzeit; „Status unbekannt“ zählt nie.
- Opencast: „Verarbeitung in Opencast fehlgeschlagen“, „Aufzeichnung auf dem Rekorder fehlgeschlagen“.
- 30-Minuten-Regel: „Aufzeichnung wurde nicht gestartet“ (30 Minuten nach dem Ende noch geplant) und „Aufzeichnung wurde nicht abgeschlossen“ (30 Minuten nach dem Ende noch in Aufnahme oder Übernahme). Beides nur, wenn ein erfolgreicher Opencast-Abgleich nach diesen 30 Minuten den Status bestätigt hat. Laufende Verarbeitung ist kein Problem.
Nach Änderungen an der .env die Container neu erzeugen
(docker compose -f docker-compose.prod.yml up -d), denn ein bloßer Neustart
liest die Datei nicht neu ein.
Ein eigenes Konto nur mit Leserechten anlegen, mit den Rollen:
ROLE_APIROLE_API_CAPTURE_AGENTS_VIEWROLE_API_EVENTS_VIEWROLE_API_EVENTS_SCHEDULING_VIEW
Außerdem muss das Konto die geplanten Events lesen dürfen. Das ist der
häufigste Stolperstein: Die External API filtert /api/events nach den
Event-ACLs. Fehlt dem Konto das Leserecht, antwortet die API zwar fehlerfrei,
die Terminliste ist aber leer oder zeigt nur wenige alte Termine.
- Eine Rolle des Kontos braucht Leserecht in den Event-ACLs, am einfachsten über die ACL-Vorlagen, mit denen die Termine angelegt werden.
- Rollen der Form
ROLE_CAPTURE_AGENT_<NAME>helfen nicht: Sie stehen nicht in den Event-ACLs. - Der Kalender der Capture Agents (
/recordings/calendars) verlangt in der Standard-SicherheitskonfigurationROLE_CAPTURE_AGENToderROLE_ADMIN. - Übergangsweise hat sich
ROLE_ADMINbewährt (ohne sie sah ein Konto nur vier alte Events). Das ist weitreichend; ansehBAR benutzt trotzdem nur lesende Aufrufe. Eine engere Rolle wird mit den Betreibern geklärt.
Ist die Rechtelage unklar, zeigt ansehBAR einen Hinweis: Sind Agents bekannt, aber keine geplanten Termine sichtbar, steht im Banner „Opencast zeigt keine geplanten Aufzeichnungen – Rechte des Kontos prüfen“.
Meldet Opencast eine HTML-Seite „Opencast :: Forbidden“, auch mit HTTP-Status 200, gilt das als „keine Berechtigung“ und nicht als gültige Antwort.
Prüfen von der Kommandozeile (Benutzer und Passwort werden abgefragt):
curl -u ansehbar https://<opencast>/api/agents
curl -u ansehbar "https://<opencast>/api/events?withscheduling=true"Die erste Antwort muss die Capture Agents der Rekorder zeigen, die zweite die geplanten Termine.
- Standard: Agent-ID und Stream-Name sind gleich (case-sensitiv).
- Abweichender Name: Die Agent-ID als
agent_idbeim Rekorder in dersite.local.jsoneintragen oder unter Verwaltung → Rekorder pflegen. - Neue Agents: Ein Agent ohne passenden Rekorder wird als Rekorder mit leerem Raumnamen angelegt und erscheint als „Neu – bitte prüfen“. Speichern im Bearbeiten-Formular der Verwaltung oder Deaktivieren markiert ihn als geprüft.
- Doppelter Rekorder: Heißt der Agent anders als der Stream des
vorhandenen Rekorders, legt der Abgleich zunächst einen zweiten Rekorder
(Stream-Name = Agent-ID) an. Dann zuerst beim automatisch angelegten
Rekorder
agent_idleeren und ihn deaktivieren, danach die Agent-ID beim richtigen Rekorder eintragen (eine Agent-ID kann nur an einem Rekorder stehen).
Unter Verwaltung → Rekorder löst „Opencast jetzt abgleichen“ sofort einen Abgleich aus, im Fehlerbanner heißt der Knopf „Jetzt abgleichen“. Er startet nur den lesenden Abgleich (ansehBAR schreibt nie nach Opencast), zeigt „Abgleich läuft …“ und danach die Zeit des letzten Abgleichs. Fehler erscheinen sofort im Banner, nicht erst nach drei Intervallen.
- Nur deaktivierte Rekorder lassen sich löschen (Papierkorb-Knopf mit Bestätigung). Aktive Rekorder nicht: erst deaktivieren.
- Beim Löschen verschwinden auch Status und Termine des Rekorders.
- Stammt der Rekorder aus Opencast, kommt seine Agent-ID auf die Liste „Ignorierte Opencast-Agents“; der Abgleich legt ihn nicht wieder an. „Wieder zulassen“ nimmt sie von der Liste. Der Agent erscheint dann beim nächsten Abgleich als „Neu – bitte prüfen“.
- Rekorder aus Opencast tragen in der Oberfläche das Opencast-Logo.
Zum Ausprobieren eignet sich der öffentliche Opencast-Testserver; die
Demo-Zugangsdaten stehen auf seiner Startseite. Nur in die lokale .env
eintragen, nie ins Repository.
https://<host>öffnen und mit einem Konto anmelden, das in der Gruppe oder inANSEHBAR_BOOTSTRAP_USERSsteht.- Unter Verwaltung → Rekorder prüfen, ob die Liste stimmt. Neue Rekorder lassen sich hier anlegen, bestehende bearbeiten oder deaktivieren.
- Unter Verwaltung → Einstellungen stehen die Stream-URL-Vorlage (mit Vorschau) und die „Toleranz bis „Stream beendet““. Ein Stream gilt als live, solange sich seine Media-Sequence innerhalb von Toleranz × Segmentdauer ändert; Standard 3, erlaubt 2 bis 10. Außerdem die Aufzeichnungs-Slots: Länge (Standard 120 Minuten, erlaubt 15 bis 480) und Beginn nach Mitternacht (Standard 0, also Slots zu geraden Stunden; muss kürzer als die Länge sein). Die Übersicht gruppiert „Heute noch geplant“ und „Morgen“ nach diesen Slots und markiert Termine, deren Beginn oder Ende vom Slot abweicht.
- Unter Verwaltung → Einladungen weitere Personen ohne Gruppenmitgliedschaft freischalten.
- Unter Verwaltung → Alarme Empfänger für Alarm-E-Mails eintragen (siehe Abschnitt 7).
- Sobald Gruppe und Einladungen tragen, kann
ANSEHBAR_BOOTSTRAP_USERSwieder geleert werden.
ansehBAR alarmiert, wenn während eines Opencast-Termins der Stream fehlt
(nur mit Opencast-Anbindung, siehe Abschnitt 5). Außerhalb von Terminen ist
„kein Stream“ normal und löst nichts aus. Es gibt zwei Kanäle: E-Mail und die
Metrik-Schnittstelle /metrics für Prometheus. Letztere beschreibt
docs/monitoring.md. Entwarnungen gibt es nur per E-Mail.
Unter Verwaltung → Rekorder stellt jeder Rekorder seinen Modus ein:
| Modus | Verhalten |
|---|---|
exact (Standard) |
Alarm, wenn der Stream zum Opencast-Start plus Wartezeit fehlt |
grid |
Alarm frühestens zum Slot-Beginn plus c.t. plus Toleranz; für Einrichtungen, die anders buchen oder starten |
off |
Kein Alarm, der Vorfall wird nur erfasst |
Unter Verwaltung → Einstellungen stehen die zugehörigen Zeiten:
| Einstellung | Bedeutung | Standard |
|---|---|---|
| Wartezeit („technischer Puffer“) | Minuten nach dem Terminbeginn, bevor ein fehlender Stream zählt | 3 |
| Slots (Länge, Beginn nach Mitternacht) | Raster der Veranstaltungen, siehe Abschnitt 6 | 120 / 0 |
| c.t.-Versatz | Minuten nach dem Slot-Beginn, zu denen die Veranstaltung tatsächlich beginnt | 15 |
| Toleranz nach c.t. | Zusätzliche Minuten nach c.t. im Modus grid |
5 |
| Toleranz am Ende | Endet der Stream so kurz vor dem geplanten Ende, ist das kein Vorfall (auch nicht in der Anzeige „Stream fehlt“) | 5 |
| Alarm per E-Mail / Metriken | Schaltet je einen Kanal global ab | an |
Im Modus grid gilt als Schwelle der spätere Zeitpunkt aus „Terminbeginn plus
Wartezeit“ und „Slot-Beginn plus c.t.-Versatz plus Toleranz“. Beginnt ein
Termin erst nach c.t., wird er nicht zusätzlich verschoben.
- Pro Ausfall gibt es einen Vorfall; er wird alarmwürdig, sobald die Schwelle überschritten ist. Es werden nur Vorfälle alarmiert, deren Termin noch läuft: Alte offene Vorfälle (etwa nach einem Deploy) lösen nichts aus.
- Kommt der Stream zurück und fällt innerhalb von 60 Sekunden wieder aus (gemessen ab dem erkannten Ausfall, also dem Prüflauf, der ihn bemerkt), gilt es als derselbe Vorfall: kein neuer Alarm.
- Entwarnung: Bleibt der Stream nach einem Alarm mindestens 60 Sekunden stabil, geht eine Entwarnung an die dann aktiven Empfänger. Ohne vorherigen Alarm gibt es keine Entwarnung. Endet der Termin bei fehlendem Stream, gibt es keine Entwarnung. Fällt der Stream nach einer Entwarnung erneut aus, entsteht ein neuer Vorfall mit eigenem Alarm.
Zusätzlich zum Stream prüft der Monitor in einem eigenen Thread den Ton.
Mit ffmpeg misst er den mittleren Pegel (mean_volume, dBFS) über ein Fenster
von AUDIO_SAMPLE_SECONDS (Standard 10 s). ffmpeg ist im Docker-Image enthalten; fehlt
es, meldet der Monitor einmal einen Fehler und misst nichts. Gemessen wird nur,
wenn der Stream live ist und ein Opencast-Termin läuft. Ein Stream ohne
Audiospur zählt als still; eine fehlgeschlagene Messung (Timeout, Netzfehler)
zählt nie als Stille. Ist der Stream-Zustand „unbekannt“, wird nicht gemessen,
aber eine laufende Stille bleibt bestehen; erst „offline“, ein deaktivierter
Rekorder oder das Termin-Ende beenden sie. Liegen zwischen zwei erfolgreichen
Messungen mehr als 5 Minuten, beginnt eine Stille neu: Was dazwischen war,
weiß niemand. Ein offener Vorfall der alten Stille endet dann mit ihrer
letzten stillen Messung.
Unter Verwaltung → Einstellungen → Ton:
| Einstellung | Bedeutung | Standard | Bereich |
|---|---|---|---|
| Stille-Schwelle | Pegel (dBFS) darunter gilt als still | −50 | −90 bis −20 |
| Stille protokollieren ab | Minuten Stille, ab denen ein Vorfall „Ton fehlt“ erfasst wird | 2 | 1 bis 30 |
| Alarm bei Stille ab | Minuten Stille, ab denen alarmiert wird (nicht kürzer als „protokollieren ab“) | 15 | 5 bis 120 |
Stille zählt erst ab der Alarmschwelle des Raums: Vor Beginn der Vorlesung ist es oft still. Deshalb zählt Stille erst ab dem Zeitpunkt, ab dem auch „Stream fehlt“ alarmieren dürfte: bei „Pünktlich“ (und „Aus“) ab Terminbeginn plus Karenz, bei „Raster (c.t.)“ ab Slot-Beginn plus c.t. plus Toleranz (Standard: 10:00 + 15 + 5 = 10:20). Davor wird Stille weder protokolliert noch gezählt.
Alarm: Die erste Stille pro Termin, die mindestens „Alarm bei Stille ab“
dauert (Standard 15 Minuten), alarmiert per
E-Mail und über ansehbar_audio_silent_alarm (Regel AnsehbarAudioSilent,
Schweregrad warning). Kommt der Ton zurück, geht eine Entwarnung „Ton wieder
da“ nur per E-Mail raus. Der Alarmmodus „Aus“ unterdrückt auch diesen Alarm
(nur Protokoll). Weitere Stillen im selben Termin werden protokolliert, aber
nicht mehr alarmiert.
„Letzte Aufzeichnung“ listet nur erhebliche Stillen: solche, die alarmiert haben oder mindestens „Alarm bei Stille ab“ dauerten. Kürzere Stillen bleiben gespeichert (für die Zeitleiste in Raumansicht und Kalender), erscheinen dort aber nicht. „Stream fehlt“-Vorfälle erscheinen weiterhin alle.
Schwelle kalibrieren: Der Befehl
docker compose exec backend python manage.py measure_audio <stream> [--seconds N]gibt level: -42.1 dBFS, level: no audio track oder failed: … aus.
Einige Räume während einer Vorlesung und in der Pause messen, die Schwelle
dazwischen setzen. Hilfreich ist auch die gespeicherte Pegelkurve
(Raumansicht, Tagesansicht im Kalender): Sie zeigt den Pegelverlauf eines
Termins samt Schwelle.
Bandbreite: Jede Messung lädt den vollständigen Stream (Video und Ton,
etwa 2 bis 4 Mbit/s) für AUDIO_SAMPLE_SECONDS (Standard 10 Sekunden). Es werden nur Räume gemessen, die
live sind und einen laufenden Termin haben. Die Parallelität ist auf
AUDIO_MAX_PARALLEL begrenzt; weitere Räume kommen nacheinander dran.
Der Monitor versendet die E-Mails über SMTP. In der .env:
| Variable | Bedeutung | Standard |
|---|---|---|
EMAIL_HOST |
SMTP-Server | localhost |
EMAIL_PORT |
Port | 25 |
EMAIL_HOST_USER / EMAIL_HOST_PASSWORD |
Zugangsdaten, falls nötig ($ in Passwörtern als $$ schreiben) |
leer |
EMAIL_USE_TLS |
1 = STARTTLS, 0 = aus |
0 |
EMAIL_TIMEOUT |
Sekunden, bevor eine hängende Verbindung aufgegeben wird | 10 |
DEFAULT_FROM_EMAIL |
Absender | ansehbar@localhost |
ALARM_LANGUAGE |
Sprache der E-Mails (de/en), für alle Empfänger gleich |
de |
EMAIL_BACKEND |
Nur zum Überschreiben des SMTP-Backends, z. B. für Tests | SMTP (in der Entwicklung Konsole) |
In der Entwicklung sind keine Mail-Einstellungen nötig: Die E-Mails erscheinen
im Log des Monitors. Nach Änderungen an der .env die Container neu erzeugen
(docker compose -f docker-compose.prod.yml up -d).
Empfänger pflegt man unter Verwaltung → Alarme. Dort lässt sich auch eine
Test-E-Mail an alle aktiven Empfänger anstoßen (der Monitor versendet sie im
nächsten Zyklus). Jede Meldung steht im Protokoll SentNotification. Die Zustellung ist
idempotent: Pro Vorfall-Ereignis, Kanal und Empfänger gibt es genau eine
Meldung, auch über Neustarts des Monitors hinweg. Schlägt der Versand fehl,
versucht der Monitor es im nächsten Zyklus erneut, höchstens 5-mal pro Meldung;
danach bleibt sie mit der Fehlermeldung (last_error) liegen. Ein SMTP-Fehler
hält den Prüfzyklus nie an.
/metrics ist ohne METRICS_TOKEN aus (404). Einrichtung, Kennzahlen,
Alarmregeln (monitoring/alerts.yml) und Scrape-Beispiel
(monitoring/scrape.example.yml) stehen in monitoring.md.
Damit die Datenbank nicht unbegrenzt wächst, räumt der Monitor alte Daten auf. Zwei Fristen, einstellbar unter Verwaltung → Einstellungen → Aufbewahrung:
| Einstellung | Bedeutung | Standard | Bereich |
|---|---|---|---|
| Pegelmessungen aufbewahren | Tage, die die einzelnen Pegelmessungen (Grundlage der Pegelkurve in Raumansicht und Kalender) gespeichert bleiben | 30 | 1 bis 365 |
| Verlauf aufbewahren | Tage, die Termine, Vorfälle und Benachrichtigungsprotokoll gespeichert bleiben | 400 | 183 bis 3650 |
Gelöscht wird, was älter als die jeweilige Frist ist:
- Pegelmessungen: alle Messungen vor der Frist.
- Verlauf: Benachrichtigungen (Protokoll gesendeter Alarme) vor der Frist; Vorfälle, die vor der Frist begannen und deren Termin ebenfalls vor der Frist endete (oder die keinen Termin haben); Termine, die vor der Frist endeten.
Der Monitor räumt höchstens einmal pro Stunde auf, bei run_monitor --once
immer. Schlägt das Aufräumen fehl, steht der Fehler im Log und der Monitor
läuft weiter.
Der Opencast-Abgleich holt nur Termine der letzten OPENCAST_LOOKBACK_DAYS
Tage (Standard 7) zurück. Einmal gelöschte alte Termine kommen deshalb nicht
wieder; die Aufbewahrung ist endgültig.
| Beobachtung | Ursache und Abhilfe |
|---|---|
| Nach der Anmeldung erscheint „Kein Zugang“ | Person ist weder in der Gruppe noch eingeladen, oder der Gruppen-Claim kommt nicht an. Mapper prüfen (Claim-Name groups, für Userinfo aktiv, ohne vollen Pfad) und neu anmelden. |
| Anmeldung schlägt fehl oder landet in einer Schleife | Redirect-URI beim Anbieter, PUBLIC_BASE_URL, DJANGO_ALLOWED_HOSTS und CSRF_TRUSTED_ORIGINS vergleichen; OIDC_OP_ISSUER muss vom Server aus erreichbar sein. |
| Alle Rekorder „Status unbekannt“ | Der Monitor erreicht den Streaming-Server nicht (DNS, Firewall, falsche URL-Vorlage). Mit docker compose -f docker-compose.prod.yml logs monitor und einem curl aus dem Container prüfen. |
| Alle Rekorder „Kein Stream“, obwohl gesendet wird | URL-Vorlage oder Stream-Namen falsch (Groß-/Kleinschreibung beachten). Die Vorschau unter „Einstellungen“ zeigt die erzeugte URL. |
| Kachel zeigt „live“, aber das Video bleibt schwarz oder „Wiedergabe gestört“ | Meist fehlende CORS-Header am Streaming-Server, oder das Gerät erreicht den Streaming-Server nicht. Browser-Konsole prüfen. |
| Banner „Monitor liefert keine Daten seit …“ | Der Container monitor läuft nicht oder hängt: docker compose -f docker-compose.prod.yml ps und logs monitor. Ohne Monitor bleibt der zuletzt bekannte Status stehen, das Banner warnt davor. |
| Pegelanzeige bleibt grau | Der Browser gibt Audio erst nach einem Klick frei: „Pegel & Ton aktivieren“ drücken. Auf Geräten, die HLS nativ abspielen, steht „Pegel nicht verfügbar“. |
| Banner „Opencast-Daten veraltet“ | Der letzte erfolgreiche Abgleich ist länger als drei Abgleich-Intervalle (OPENCAST_SYNC_SECONDS) her, oder es gab noch gar keinen erfolgreichen Abgleich (etwa kurz nach dem Start). Solange das Banner steht, zeigen Kachel und Raumansicht nicht „Kein Stream – keine Aufzeichnung geplant“. docker compose -f docker-compose.prod.yml logs monitor zeigt die Fehlerart (opencast=error): Adresse, Zugangsdaten und Erreichbarkeit prüfen, mit dem curl aus Abschnitt 5 gegenprobieren. Die Stream-Prüfung läuft unabhängig davon weiter. |
| Banner „Opencast nicht erreichbar“ | Adresse, Netz, DNS oder Firewall prüfen; mit dem curl aus Abschnitt 5 gegenprobieren. |
| Banner „Opencast hat die Anmeldung abgelehnt“ | Benutzer oder Passwort falsch. Enthält das Passwort ein $, in der .env $$ schreiben, und Container neu erzeugen. |
| Banner „Keine Berechtigung in Opencast“ | Dem Konto fehlen API-Rollen oder Rechte; auch Opencasts HTML-Seite „Forbidden“ mit Status 200 wird so gemeldet. Rollen aus „Konto in Opencast“ prüfen. |
| Banner „Opencast antwortet nicht rechtzeitig“ | Opencast antwortet zu langsam; Last und Netz prüfen. Der nächste Abgleich versucht es erneut. |
| Banner „Opencast-Serverfehler“ oder „Unerwartete Antwort von Opencast“ | Fehler auf Opencast-Seite oder falsche Adresse (z. B. Proxy-Seite statt API). Logs von Opencast und Monitor prüfen. |
| Banner „Interner Fehler beim Opencast-Abgleich“ | Der Abgleich scheiterte an ansehBAR selbst (meist der Datenbank), nicht an Opencast. Log des Monitors prüfen (docker compose -f docker-compose.prod.yml logs monitor). |
| Banner „Opencast-Abgleich abgeschaltet – OPENCAST_URL muss https:// verwenden“ | OPENCAST_URL beginnt mit http://. Ohne TLS ginge das Passwort im Klartext über das Netz, deshalb gleicht ansehBAR nicht ab (außer mit DJANGO_DEBUG=1). Adresse auf https:// umstellen und Container neu erzeugen. |
| Hinweis „Opencast zeigt keine geplanten Aufzeichnungen“ | Agents sind bekannt, aber das Konto sieht keine Termine: Event-ACL-Rechte des Kontos prüfen (siehe „Konto in Opencast“). |
| Termine fehlen, obwohl in Opencast geplant | Meist darf das Konto die Events nicht lesen: Rolle in den Event-ACLs bzw. ACL-Vorlagen ergänzen (siehe „Konto in Opencast“). Außerdem liegt der Termin vielleicht außerhalb von OPENCAST_LOOKAHEAD_DAYS, oder der Agent ist keinem Rekorder zugeordnet. |
| E-Mails kommen nicht an | Zuerst docker compose -f docker-compose.prod.yml logs monitor prüfen. Offene Meldungen zeigt das Protokoll: docker compose -f docker-compose.prod.yml exec app python manage.py shell -c "from alarms.models import SentNotification as S; print(list(S.objects.filter(sent_at__isnull=True).values('recipient', 'attempts', 'last_error')))". last_error nennt den SMTP-Fehler (Server, Port, Zugangsdaten, EMAIL_USE_TLS). Ohne EMAIL_HOST geht die Mail an localhost:25 und kommt meist nirgends an. Nach 5 Fehlversuchen versucht der Monitor die Meldung nicht mehr; Einstellung korrigieren und eine Test-E-Mail senden. Außerdem: Ist der Alarmmodus des Rekorders off, ist „Alarm per E-Mail“ abgeschaltet, oder fehlen Empfänger, wird nichts gesendet. |
| Keine Alarme trotz fehlendem Stream | Alarme gibt es nur während eines Opencast-Termins, nach Wartezeit (bei grid nach c.t. plus Toleranz) und nur für Vorfälle, deren Termin noch läuft. Modus, Opencast-Anbindung und Banner prüfen. |
| Dialog meldet „Das Ticket konnte in GitLab nicht angelegt werden.“ | GitLab ist nicht erreichbar oder lehnt die Anfrage ab: URL, Token (abgelaufen? Rolle Reporter, Scope api?) und Projekt prüfen. Weiterleitungen folgt ansehBAR nie (ein Redirect auf einen anderen Host zählt als Fehler). Das Token steht nie in Meldungen oder Logs. |
| Meldung „GitLab-Tickets sind nicht konfiguriert.“ oder Knopf fehlt | URL oder Token fehlen, oder das Token ist unlesbar (Schlüssel geändert, siehe Abschnitt 9): unter „Einstellungen“ neu eintragen (der Knopf erscheint nach dem Speichern ohne Neuladen). |
| Ticket ohne Screenshot, Hinweis „Der Screenshot-Upload zu GitLab ist fehlgeschlagen; kein Bild angehängt.“ | Der Upload scheiterte (Größe über 5 MB, Rechte), das Ticket wurde trotzdem angelegt. |
| Agent wird übersprungen | Der Log des Monitors nennt per WARNING den Grund: Die Agent-ID ist kein gültiger Stream-Name (erlaubt sind Buchstaben, Ziffern, ., _, -), oder zu lang (mehr als 100 Zeichen), oder der Stream-Name gehört schon zu einem anderen Agent. agent_id beim passenden Rekorder setzen. |
Aus der Übersicht lässt sich zu einem Raum ein Ticket in GitLab anlegen, mit
Fehlerbeschreibung, Status, aktuellem Opencast-Termin und einem Screenshot des
Streams. ansehBAR speichert dabei nichts; es sendet nur an GitLab
(POST …/uploads und POST …/issues). Ohne Eintrag unter „Einstellungen“ ist
die Funktion aus und der Knopf erscheint nicht.
- In GitLab ein privates Projekt für die Tickets wählen oder anlegen. Nur ein kleiner Kreis sollte Mitglied sein: Screenshots können Personen im Hörsaal zeigen und liegen danach in GitLab.
- Im Projekt unter Einstellungen → Zugriffstoken ein Project Access Token anlegen: Rolle Reporter, nur der Scope api, Ablaufdatum setzen.
- In ansehBAR unter Verwaltung → Einstellungen, Abschnitt „GitLab-Tickets“,
die GitLab-Projekt-URL (vollständig, mit Untergruppen, nur
https://, z. B.https://gitlab.example.com/gruppe/projekt) und das Zugriffstoken eintragen und speichern. Das Token ist nur schreibbar: danach steht dort „Token gesetzt“, es wird nie wieder angezeigt. Mit „Token entfernen“ löschen Sie es. - Wer die Übersicht geöffnet hat, lädt sie neu; dann erscheint der Knopf „Ticket für ‹Raumname› erstellen“ an jeder Kachel.
Wichtig: Ändern Sie die URL, ohne ein neues Token einzugeben, löscht ansehBAR das gespeicherte Token (es soll nie an ein anderes Ziel geschickt werden). Tragen Sie bei einem URL-Wechsel das neue Token gleich mit ein.
Das Token liegt verschlüsselt (Fernet) in der Datenbank. Der Schlüssel kommt aus
TOKEN_ENCRYPTION_KEY in der .env; ist sie leer, wird er aus
DJANGO_SECRET_KEY abgeleitet. Einen Schlüssel erzeugen Sie auf dem Server
ohne weitere Pakete mit openssl (32 Zufallsbytes in URL-sicherem Base64,
44 Zeichen):
openssl rand -base64 32 | tr '+/' '-_'Ein gesetzter, aber ungültiger Schlüssel wird beim Start bemängelt
(manage.py check, Fehler common.E001); das Speichern eines Tokens wird dann
abgelehnt.
Ändern sich TOKEN_ENCRYPTION_KEY oder (ohne eigenen Schlüssel)
DJANGO_SECRET_KEY später, ist das gespeicherte Token unlesbar: ansehBAR
behandelt es als nicht gesetzt, und Sie tragen es unter „Einstellungen“ neu ein.
Sichern Sie den Schlüssel mit der .env (siehe docs/deployment.md,
Abschnitt „Sicherung und Wiederherstellung“).
Titel: <Raum> (<Stream>): <erste Zeile der Fehlerbeschreibung>. Beschreibung:
Fehlerbeschreibung, Raum, Stream und Capture-Agent, Zeitpunkt, Status (live
seit / offline seit / Stille / Pegel / Agent-Zustand), aktueller
Opencast-Termin (Titel, Serie, Vortragende, geplante Zeit, Status), die
erstellende Person, ein Link zur Raumansicht und der Screenshot. Labels und
Zuständige setzt ansehBAR nicht.
Der Screenshot ist das aktuelle Vorschaubild der Kachel. Zeigt die Kachel kein
Video (Stream offline, Wiedergabe gestört), geht das Ticket ohne Bild raus; der
Dialog weist darauf hin. Das Bild lesen zu dürfen setzt CORS am Streaming-Server
voraus (Abschnitt 1, gilt schon für die Wiedergabe). Die Vortragenden stammen
aus dem Feld presenter der Opencast-Events (Abschnitt 5).
Updates, Sicherung und Rückkehr zu einer früheren Version beschreibt die
Installationsanleitung, Abschnitte 6 und 7.
Datenbank-Migrationen laufen beim Start des Containers app automatisch.
Die Standortkonfiguration bleibt in der Datenbank erhalten und muss nur bei
Änderungen erneut geladen werden.