MINA

MINA ist ein Matrix-Bot, mit dem man Warnmeldungen aus der NINA-API des Bundes abonnieren kann. Ein Matrix-Raum wird dabei einem Ort zugeordnet, so dass man ausschließlich Warnmeldungen für den jeweiligen Ort erhält.

Status

Beta. Nach ersten Tests scheint der Bot grundlegend zu funktionieren.

Bot benutzen

Wenn man die Matrix-ID eines bereits existierenden MINA-Bots kennt, kann man diesen einfach einladen und ihm dann Kommandos geben.

⚠️ Aktuell benötigt der Bot einen unverschlüsselten Matrix-Raum und Moderationsrechte in diesem Raum. Es ist daher empfehlenswert, für die Nutzung einen separaten Raum einzurichten.

Man kann in einem Raum nur Warnmeldungen für einen einzelnen Ort erhalten. Wenn man für mehrere Orte gewarnt werden möchte, muss man daher mehrere Räume erstellen.

Und so gehts:

Bot in einen unverschlüsselten Raum einladen
Moderatorenrechte an den Bot vergeben
Mit !suche <Ort> die ID für einen Ort suchen
Mit !abonniere <ID> die Warnmeldungen für den gewählten Ort abonnieren

Der Bot prüft alle 10 Minuten, ob es neue Warnmeldungen für den jeweiligen Ort gibt, und postet diese dann in den Raum.

Bot installieren

Man kann den Bot entweder manuell installieren oder per Docker nutzen. In beiden Fällen muss vorher ein Matrix-Account für den Bot eingerichtet werden.

Matrix-Account einrichten

Matrix-User für den Bot anlegen
Access token holen (z.B. mit Riot als Bot einloggen und dann Alle Einstellungen => Hilfe und Über => Zugriffstoken einsehen und rauskopieren. Danach nicht! aus Riot ausloggen, sondern nur das Fenster schließen!)

Manuell installieren

Voraussetzungen:

NodeJS 14
direnv

Bot installieren und einrichten:

Repo auschecken
npm run build
cp .env.example .env
HOMESERVER_URL und ACCESS_TOKEN in der Datei .env hinterlegen

Bot starten:

npm start

Per Docker installieren

Es gibt ein fertiges Docker-Image unter decentralize/nina-matrix-bot. Alternativ kann man es in diesem Repository selbst bauen.

Man kann den Container beispielsweise wie folgt starten:

docker run \
  -e HOMESERVER_URL=https://... \
  -e ACCESS_TOKEN=... \
  -e INTERVAL_MINUTES=10 \
  decentralize/nina-matrix-bot

Details zur Funktionsweise

Die Zuordnung des gewählten Raums zum jeweiligen Chat-Raum wird als Room state im jeweiligen Matrix-Raum gespeichert. (Auch die zuletzt gepostete Warnung wird dort hinterlegt). Aus diesem Grund benötigt der Bot Moderatorenrechte. (Dies kann möglicherweise in Zukunft anders gelöst werden.)
Die Häufigkeit der Abfrage der Warnmeldungen wird über die Env-Variable INTERVAL_MINUTES festgelegt.
Über die Variable FEEDBACK_ROOM kann man einen Matrix-Raum angeben, der vom Hilfe-Befehl als Support-Channel angezeigt bzw. verlinkt wird.
Man kann einen (unverschlüsselten) Admin-Raum anlegen und den Bot dahin einladen. Die ID des Raums muss man dann in der Variable ADMIN_ROOM_ID hinterlegen. In diesem Raum postet der Bot dann automatisch verschiedene Statusmeldungen.
Der Sync-Status mit dem Matrix-Server wird standardmäßig in der lokalen Datei bot.json gespeichert. Wenn eine Persistenz auf Dateisystem-Ebene nicht möglich ist, kann stattdessen ein Redis-Server benutzt werden. Dafür muss die Env-Variable REDIS_URL gesetzt werden (z.B. auf redis://localhost). Siehe auch das Beispiel in der docker-compose.yml. (Der Redis-Server selbst muss nicht zwingend für Persistenz konfiguriert werden. Wenn er neugestartet wird, schreibt der Bot bei der nächsten Verbindung sofort wieder alle Werte neu in Redis rein.)
Optional kann der Bot regelmäßig ein Lebenssignal senden, um darüber zu informieren, dass er noch läuft. Dafür braucht man eine Monitoring-Software, die per Webhook dieses Ping-Signal entgegen nimmt. Empfehlenswert ist z.B. Healthchecks.

In dem jeweiligen Monitoring-System legt man einen neuen Check an, kopiert dann die Ziel-URL und setzt dann bei MINA die Env-Variablen HEALTHCHECK_URL (Ziel-URL für den Ping) und HEALTHCHECK_PING_INTERVAL_IN_SECONDS (Ping-Interval in Sekunden) entsprechend.

Entwicklung

Voraussetzungen

Es handelt sich um eine NodeJS-Anwendung. Installiert sein muss:

NodeJS (>= 14)

Einrichten

Zur Einrichtung muss (analog zum normalen Setup) zuerst die Konfiguration festgelegt werden:

cp .env.example .env
HOMESERVER_URL und ACCESS_TOKEN in der Datei .env hinterlegen. (Dafür braucht man einen Matrix-Account, siehe oben.)

Kompilieren und Ausführen

Die TypeScript-Dateien müssen nach JavaScript kompiliert werden. In einem Terminal Folgendes ausführen:

npm run watch

In einem anderen Terminal kann nun parallel die App gestartet werden:

source .env
npm start

Nach jeder Änderung im Sourcecode muss die App beendet und per npm start erneut gestartet werden.

Tests

Es gibt automatisierte Tests, die mit Hilfe von Jest implementiert wurden. Sie können über folgenden Befehl ausgeführt werden:

npm run test

Lizenz

Damit diese Software nicht ähnlich unter Verschluss gerät wie die Warn-Schnittstellen des Bundes, wird der Code unter der AGPLv3 veröffentlicht.

Haftungsausschluss

Die Entwickler übernehmen keine Garantie dafür, dass der Bot fehlerfrei funktioniert und alle Warnungen zuverlässig zugestellt werden. Die Software befindet sich in der Entwicklung und es fehlen unter anderem noch Diagnose-Möglichkeiten, die bei Fehlfunktionen des Bots Alarm schlagen.

Es ist daher zu empfehlen, zusätzlich weitere Quellen für Warnmeldungen zu verwenden. Wie z.B. FediNINA im Fediverse.

Beteiligung

Pull-Requests sind willkommen! Allerdings bitte darauf achten, die ESLint-Richtlinien einzuhalten.

Danksagung

Ein großer Dank gebührt den Menschen hinter bund.dev, die sich die Mühe gemacht haben, bisher undokumentierte Schnittstellen von Behörden und Institutionen mit öffentlichen Daten für die Allgemeinheit nutzbar zu machen.

djmaze / nina-matrix-bot