Files
Sternsinger/CMBNet/README_CMBNet.md
T

115 lines
4.8 KiB
Markdown

# CMBNet
Webanwendung für die Verwaltung von Straßen und Gruppen mit Kartendarstellung.
## Setup
```bash
cd CMBNet
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdir -p instance logs data migrations
flask --app cmbnet init-db
flask --app cmbnet run --debug --host 127.0.0.1 --port 5000
```
## Zugriff
Öffne http://127.0.0.1:5000 und wähle einen Mandanten (BV, RV, SV).
## Betrieb hinter einem Reverse-Proxy (URI-Prefix)
Die Anwendung kann unter einem beliebigen Pfad ausgeliefert werden, z. B.
`https://example.com/cmbnet/`. Dazu muss der Proxy den öffentlichen Prefix im
Header `X-Forwarded-Prefix` setzen:
```caddyfile
example.com {
redir /cmbnet /cmbnet/ 308
handle_path /cmbnet/* {
reverse_proxy 127.0.0.1:5000 {
header_up X-Forwarded-Prefix /cmbnet
}
}
}
```
Die Middleware in `cmbnet/__init__.py` setzt daraus `SCRIPT_NAME`, sodass
`url_for` alle Links, Formularziele und statischen Dateien mit Prefix erzeugt.
Der Prefix wird außerdem als `CMBNET_BASE_URL` an JavaScript übergeben; AJAX-
und WebSocket-Aufrufe bilden ihre URLs damit korrekt. Eine vollständige
Beispielkonfiguration (auch für Proxys, die den Prefix nicht entfernen) steht
in `Caddyfile.example`.
Wichtig: Der Flask-Port sollte nur für den Reverse-Proxy erreichbar sein, damit
Clients den Header nicht selbst setzen können.
## WebSocket-Synchronisierung
Jede Webview erzeugt beim Laden einmalig eine Client-ID. Sie wird bewusst nicht
in `sessionStorage` gespeichert: Ein Seiten-Reload erzeugt eine neue Client-ID
und damit eine neue Broker-Verbindung. Nicht zustellbare Nachrichten mit
Code >= 100 werden beim Broker pro `(Mandant, Client-ID)` gepuffert und bei der
nächsten WebSocket-Verbindung mit derselben Client-ID ausgeliefert. Mehrere
Clients desselben Accounts werden getrennt verwaltet und alle beliefert.
Die Zeitfenster lassen sich über Umgebungsvariablen konfigurieren:
- `CMBNET_WS_QUEUE_MAX_AGE_MINUTES` (Default `15`): Maximales Alter einer
Client-Queue. Ältere Queues werden verworfen; beim nächsten Reconnect mit
derselben Client-ID wird stattdessen eine Code-99-Nachricht mit Hinweis auf
die zu lange Unterbrechung zugestellt.
- `CMBNET_WS_CLIENT_RETENTION_MINUTES` (Default `60`): Wie lange eine nicht mehr
verbundene Webview samt Queue registriert bleibt, bevor der Broker sie
endgültig aufräumt.
- `CMBNET_WS_GROUP_ONLINE_TIMEOUT_SECONDS` (Default `120`): Zeit ohne Code-2-
Lebenszeichen, nach der eine Gruppe von `online` auf `unterwegs` wechselt.
- `CMBNET_WS_DEBUG_MESSAGES` (Default `1`): schreibt jede beim Broker
eingehende Nachricht inklusive Absender, Client-ID, Code und ermitteltem
Empfängerkreis nach `logs/cmbnet-ws-YYYY-MM-DD.log`. Mit `0` lässt sich die
Ausgabe abschalten.
- `CMBNET_WS_BUS_POLL_INTERVAL` (Default `0.5`): Intervall in Sekunden, in dem
jeder Worker die gemeinsame Queue für seine lokal verbundenen Clients prüft.
- `CMBNET_WS_EPHEMERAL_TTL_SECONDS` (Default `30`): Lebensdauer kurzlebiger
Code-2-Zustellaufträge.
- `CMBNET_WS_WORKER_ID`: optionale feste Worker-ID; muss je Worker-Prozess
eindeutig sein. Standardmäßig wird `<hostname>:<pid>` verwendet.
Die Client-Queues und Sequenznummern liegen in der gemeinsamen SQLite-Datenbank
(`ws_clients`, `ws_client_queue`). Dadurch überstehen sie einen Worker-Neustart
und einen Reconnect auf einem anderen WSGI-Worker. Jeder Worker betreibt eine
eigene Zustellschleife und liefert nur an seine lokal verbundenen Clients aus.
Die Latenz für workerübergreifende Nachrichten ergibt sich aus
`CMBNET_WS_BUS_POLL_INTERVAL` (Default `0.5` Sekunden). Der mobile Client
puffert zusätzlich ausgehende fachliche Nachrichten kurzzeitig im Speicher und
sendet sie nach erfolgreicher Authentifizierung automatisch nach.
Für den Betrieb mit mehreren Workern muss Gunicorn ohne `preload_app` laufen,
damit Heartbeat und Zustellschleife in jedem Worker-Prozess starten:
```bash
gunicorn --worker-class gevent --workers 4 --bind 127.0.0.1:5000 wsgi:app
```
SQLite läuft dabei im WAL-Modus mit einem `busy_timeout`. Bei sehr vielen
Clients oder hoher Schreiblast sollte statt SQLite ein Redis- oder
PostgreSQL-Bus verwendet werden.
Eine ausführliche Beschreibung des Protokolls, der Brokerlogik, der
Nebenläufigkeit und der aktuellen Abweichungen steht in
[`../doc/broker.md`](../doc/broker.md).
## Erste Einrichtung
Nach der Initialisierung der Datenbank müssen noch Mandanten und ein Admin-Account angelegt werden.
```bash
sqlite3 instance/cmbnet.sqlite3
INSERT INTO tenants (code, name) VALUES ('BV', 'Bezirk BV'), ('RV', 'Bezirk RV'), ('SV', 'Bezirk SV');
INSERT INTO accounts (tenant_id, name, password_hash, role) VALUES (2, 'admin', '...', 'Administrator');
```
Für den Passwort-Hash kann `python3 -c "from werkzeug.security import generate_password_hash; print(generate_password_hash('admin'))"` verwendet werden.