Files
Sternsinger/CMBNet/docs/FCM_HOWTO.md
T

10 KiB
Raw Blame History

Firebase/FCM einrichten – Howto

Dieses Dokument beschreibt die praktischen Schritte, um die im Code vorbereiteten FCM-Aufwachsignale für die mobilen PWA-Ansichten zu aktivieren. FCM überträgt ausschließlich das Signal; Nachrichten und Positionen laufen weiterhin über WebSocket und die Broker-Queue. Die Architektur und die Plattformgrenzen stehen in FCM_ARCHITEKTUR.md.

Voraussetzungen

  • Ein Google-Konto und Zugriff auf die Firebase Console.
  • Die CMBNet-Installation läuft über HTTPS (auch im Test). Web Push und Service Worker funktionieren nicht über eine reine HTTP-Adresse, außer auf localhost.
  • Die mobile Ansicht ist als PWA installiert (zum Home-Bildschirm hinzugefügt). Besonders auf iOS/iPadOS ist das Voraussetzung für Web Push.
  • Python-Umgebung der Anwendung kann Pakete installieren.

1. Firebase-Projekt anlegen

  1. In der Firebase Console Projekt hinzufügen wählen.
  2. Projektnamen vergeben (z. B. cmbnet-push) und die Analytics-Option nach Bedarf aktivieren. Für FCM ist Analytics nicht erforderlich.
  3. Nach dem Anlegen die Projekt-ID notieren. Sie wird später als CMBNET_FCM_PROJECT_ID bzw. CMBNET_FCM_WEB_PROJECT_ID verwendet.

2. Web-App registrieren

  1. In den Projekteinstellungen → Allgemein unter Meine Apps die Plattform Web (</>) hinzufügen.

  2. Einen Spitznamen vergeben und die App registrieren.

  3. Den angezeigten firebaseConfig-Block notieren. Er enthält ausschließlich öffentliche Werte:

    {
      apiKey: "...",
      authDomain: "cmbnet-push.firebaseapp.com",
      projectId: "cmbnet-push",
      storageBucket: "cmbnet-push.appspot.com",
      messagingSenderId: "...",
      appId: "..."
    }
    

    Diese Werte sind keine Geheimnisse und werden vom Server an Browser und Service Worker ausgeliefert. Der Service-Account aus Schritt 4 darf dagegen niemals in eine Webseite oder in das Repository gelangen.

3. Cloud Messaging und VAPID-Schlüssel

  1. In der Firebase Console unter Cloud Messaging die Web-Push- Konfiguration öffnen.
  2. Falls noch kein Schlüsselpaar existiert, unter Web-Push-Zertifikate ein Schlüsselpaar erzeugen.
  3. Den angezeigten VAPID-Schlüssel (öffentlicher Schlüssel) notieren. Er wird als CMBNET_FCM_VAPID_KEY benötigt.
  4. Die Web-Push-Konfiguration muss zum selben Firebase-Projekt wie die Web-App gehören.

4. Service-Account für den Server erzeugen

  1. In der Firebase Console Projekteinstellungen → Dienstkonten öffnen.

  2. Neuen privaten Schlüssel generieren wählen und die JSON-Datei herunterladen.

  3. Die Datei außerhalb des Repositories ablegen, z. B. /etc/cmbnet/firebase-service-account.json, und nur für den Anwendungsbenutzer lesbar machen:

    sudo install -m 600 firebase-service-account.json \
        /etc/cmbnet/firebase-service-account.json
    
  4. Alternativ kann der JSON-Inhalt als eine Zeile in CMBNET_FCM_SERVICE_ACCOUNT_JSON gesetzt werden. Für den Dauerbetrieb ist eine Datei mit restriktiven Rechten vorzuziehen, weil Umgebungsvariablen leichter in Prozesslisten oder Logs auftauchen.

5. Python-Abhängigkeit installieren

FCM nutzt das optionale Paket firebase-admin. Es ist in requirements.txt eingetragen, muss aber in der aktiven Umgebung installiert sein:

cd CMBNet
source .venv/bin/activate
pip install -r requirements.txt

Ohne dieses Paket startet die Anwendung weiterhin; FCM bleibt dann deaktiviert und protokolliert einen entsprechenden Hinweis.

6. Umgebungsvariablen setzen

Die Anwendung liest die Konfiguration aus Umgebungsvariablen (siehe config.py). Ein vollständiges Beispiel für einen Dienstmanager oder eine .env-Datei:

CMBNET_FCM_ENABLED=1

# Serverseitiger Versand
CMBNET_FCM_PROJECT_ID=cmbnet-push
CMBNET_FCM_SERVICE_ACCOUNT_FILE=/etc/cmbnet/firebase-service-account.json
# Alternativ statt der Datei:
# CMBNET_FCM_SERVICE_ACCOUNT_JSON={"type":"service_account",...}

# Öffentliche Web-Konfiguration aus Schritt 2
CMBNET_FCM_WEB_API_KEY=...
CMBNET_FCM_WEB_AUTH_DOMAIN=cmbnet-push.firebaseapp.com
CMBNET_FCM_WEB_PROJECT_ID=cmbnet-push
CMBNET_FCM_WEB_STORAGE_BUCKET=cmbnet-push.appspot.com
CMBNET_FCM_WEB_MESSAGING_SENDER_ID=...
CMBNET_FCM_WEB_APP_ID=...

# Web-Push aus Schritt 3
CMBNET_FCM_VAPID_KEY=...

# Optional: Zeitverhalten
CMBNET_FCM_OFFLINE_WAKE_MINUTES=5
CMBNET_FCM_QUEUE_WAKE_COOLDOWN_SECONDS=60
CMBNET_FCM_MANUAL_WAKE_COOLDOWN_SECONDS=15
CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS=30

Die Datei mit den Umgebungsvariablen muss dieselben Rechte wie die Service-Account-Datei besitzen. Nach Änderungen den WSGI-Prozess neu starten; Python liest die Werte beim Start.

Prüfen, ob die Konfiguration vollständig ist

public_fcm_config() aktiviert FCM nur, wenn CMBNET_FCM_ENABLED gesetzt ist und API-Key, Projekt-ID, Sender-ID, App-ID und VAPID-Schlüssel vorhanden sind. Prüfen lässt sich das über die vom Server erzeugte Datei:

curl -s https://example.com/fcm-sw-config.js

Erwartet wird ein JavaScript-Objekt mit "enabled": true und gefüllten firebase-Werten. Bei "enabled": false fehlt mindestens einer der oben genannten Werte oder firebase-admin ist nicht installiert.

7. Datenbankmigration

Beim nächsten Start führt ensure_schema() die idempotenten Migrationen aus. Neu sind die Spalten ws_clients.client_type, ws_clients.last_wake_at, ws_clients.last_wake_reason sowie die Tabelle ws_push_tokens. Eine manuelle Migration ist nicht nötig; ein Backup der SQLite-Datei vor dem ersten Start ist trotzdem empfehlenswert.

8. Mobile PWA installieren und Benachrichtigungen erlauben

  1. Die mobile Ansicht (Gruppen-View bzw. mobiler Dispatcher) über HTTPS öffnen.
  2. Im Browsermenü Zum Home-Bildschirm bzw. App installieren wählen.
  3. Die PWA aus dem Home-Bildschirm starten.
  4. In den Einstellungen der mobilen Ansicht Benachrichtigungen aktivieren antippen und die Browserabfrage bestätigen.
  5. Danach lädt die Seite das Firebase-SDK, fordert ein FCM-Token an und registriert es über POST /<tenant>/api/push/register. Der Client-Typ (group_view bzw. dispatcher_mobile) wird dabei gegen die Rolle geprüft.

Auf iOS/iPadOS muss die App wirklich installiert sein; in einem normalen Safari-Tab wird kein Token registriert. Nach dem Entfernen der PWA vom Home-Bildschirm oder dem Entziehen der Benachrichtigungserlaubnis endet die Zustellung.

9. Funktion testen

Token-Registrierung prüfen

Nach dem Aktivieren der Benachrichtigungen in der Datenbank nachsehen:

sqlite3 instance/cmbnet.sqlite3 \
  "SELECT tenant_id, client_id, account_id, client_type, platform, auto_position, invalid
     FROM ws_push_tokens;"

Es muss ein Eintrag für den mobilen Client vorhanden sein. Ein leeres Ergebnis bedeutet meist: keine HTTPS-Verbindung, keine installierte PWA, keine Benachrichtigungserlaubnis oder enabled: false in fcm-sw-config.js.

Manuellen Wake auslösen

Im Desktop-Dispatcher oder im mobilen Dispatcher den Radar-Button antippen. Der Button ruft POST /<tenant>/api/push/wake auf. Die Antwort enthält candidates, sent und failed.

  • sent > 0: FCM hat das Signal angenommen.
  • candidates = 0: kein getrennter mobiler Client mit gültigem Token.
  • HTTP 503: FCM ist nicht vollständig konfiguriert.
  • HTTP 403: Rolle darf nicht wecken (nur Dispatcher/Administrator).

Da nur getrennte Clients geweckt werden, muss die mobile PWA vor dem Test geschlossen oder die WebSocket-Verbindung unterbrochen sein.

Offline-Timeout prüfen

CMBNET_FCM_OFFLINE_WAKE_MINUTES testweise auf 1 setzen, PWA schließen und nach ein bis zwei Minuten den Radar-Button im Desktop-Dispatcher verwenden. Bei aktiver automatischer Positionsübertragung sollte die Gruppen-View nach dem Wake eine neue Position senden. Der Service Worker zeigt nur dann eine Benachrichtigung, wenn kein PWA-Fenster erreichbar ist.

FCM-Versand direkt prüfen

Bei aktiviertem Debug-Logging des WSGI-Servers erscheinen Warnungen, wenn firebase-admin fehlt, die Initialisierung scheitert oder FCM einen Batch ablehnt. Ungültige Tokens werden als invalid markiert und nicht mehr verwendet.

Troubleshooting

Symptom Ursache / Lösung
fcm-sw-config.js liefert enabled: false CMBNET_FCM_ENABLED nicht gesetzt oder einer der Web-Werte/VAPID fehlt.
Kein Token in ws_push_tokens PWA nicht installiert, keine Benachrichtigungserlaubnis, kein HTTPS oder Client-Typ/Rolle passt nicht.
firebase-admin ist nicht installiert im Log pip install -r requirements.txt in der aktiven Umgebung ausführen.
FCM-Initialisierung fehlgeschlagen Service-Account-Datei fehlt, ist nicht lesbar oder gehört zu einem anderen Projekt.
SENDER_ID_MISMATCH bzw. Token wird ungültig Web-Konfiguration und Service-Account stammen aus verschiedenen Firebase-Projekten.
Radar-Button meldet 0 Kandidaten Der Client ist noch verbunden, hat kein Token oder wurde bereits innerhalb des Cooldowns geweckt.
iOS erhält keine Push-Nachricht PWA nicht installiert, iOS < 16.4 oder Benachrichtigungen nicht erlaubt.
Benachrichtigung erscheint, aber keine Position Kein PWA-Fenster aktiv oder Standort im Hintergrund nicht erlaubt; die letzte bekannte Position wird verwendet.
Doppelte Wakes bei mehreren Workern CMBNET_FCM_WAKE_POLL_INTERVAL_SECONDS und CMBNET_WS_BUS_POLL_INTERVAL prüfen; die Reservierung erfolgt über last_wake_at.

Sicherheit und Datenschutz

  • Der Service-Account-Schlüssel bleibt auf dem Server und gehört nicht ins Repository, in Templates oder in Browser-JavaScript.
  • FCM-Tokens sind installationsbezogene Kennungen. Sie werden nicht geloggt und beim Abmelden über DELETE /<tenant>/api/push/register entfernt.
  • Das FCM-Signal enthält nur type und reason. Mandant, Rolle, Nachricht, Absender und Position werden nicht über Firebase übertragen.
  • Firebase ist ein externer Google-Dienst. Der Betrieb muss die daraus folgenden Datenschutz- und Verfügbarkeitsanforderungen bewerten.
  • Die PWA muss über HTTPS laufen; der Server sollte nur hinter dem Reverse-Proxy erreichbar sein.