Messenger Bot¶

Diese Dokumentation beschreibt Installation, Konfiguration, Betrieb und Test des ghv-messenger-bot im Vereinsbetrieb.

Der Bot dient aktuell zur Erfassung und Genehmigung von Arbeitsstunden (Timesheets) über Matrix und exportiert aggregierte Daten für die Vereinsdokumentation (MkDocs).

Bot-Status¶

lädt

Gesamt

-

Erzeugt

-

Bot

-

Online seit

-

Letzter Fehler

-

Tasks

-

Reasons / Hinweise

-

1. Überblick¶

Zielsetzung¶

Erfassung von Arbeitsstunden per Direktchat
Genehmigungsworkflow (approve / reject)
Jahresauswertung als JSON (hours_YYYY.json)
Betriebsstatus als JSON (bot_status.json)
Erweiterbar um weitere Module (Termine, Crawler, Social Monitoring)

Architektur¶

Matrix: Synapse (keine E2EE erforderlich)
Bot: Docker-Container (GitLab Registry)
Datenbank: PostgreSQL 16 (Docker)
Exports: Host-Verzeichnis, von nginx lesbar
Doku: MkDocs, liest JSON direkt aus

Wichtige Pfade¶

Konfiguration: /etc/ghv-messenger-bot/config.toml
Persistenter State: /var/lib/ghv-messenger-bot/
Exports: /var/lib/ghv-messenger-bot/exports/
Backups: /var/backups/ghv-messenger-bot/

2. Quickstart (Testbetrieb)¶

Voraussetzungen¶

Debian Linux
Docker + Docker Compose v2
Matrix-Bot-Account existiert bereits
Zugriff auf GitLab Container Registry (Pull)

Verzeichnisse anlegen¶

sudo install -d -m 0755 /opt/ghv-messenger-bot
sudo install -d -m 0755 /etc/ghv-messenger-bot
sudo install -d -m 0755 /var/lib/ghv-messenger-bot
sudo install -d -m 0755 /var/lib/ghv-messenger-bot/exports
sudo install -d -m 0755 /var/backups/ghv-messenger-bot
````

### Bot starten

```bash
cd /opt/ghv-messenger-bot
docker compose up -d
docker compose ps

Initiale Migration & Seed¶

docker compose run --rm bot migrate run --config /etc/ghv-messenger-bot/config.toml
docker compose run --rm bot seed run --config /etc/ghv-messenger-bot/config.toml

Hinweis: Wenn role 'member' is missing erscheint, wurde seed noch nicht ausgeführt.

3. Konfiguration¶

config.toml (Beispiel)¶

Pfad: /etc/ghv-messenger-bot/config.toml

[matrix]
homeserver = "https://matrix.example.org"
user_id = "@ghv-bot:example.org"
admin_room_id = "!abcdef:example.org"

[db]
dsn = "postgresql+asyncpg://USER:PASSWORD@postgres:5432/ghvbot"

[state]
path = "/var/lib/ghv-messenger-bot/state"

[exports]
path = "/var/lib/ghv-messenger-bot/exports"

Secrets¶

MATRIX_PASSWORD – Passwort des Bot-Accounts
optional: DATABASE_URL (wenn nicht aus config genutzt)

Empfohlen: .env oder Secrets-Management, keine Klartext-Passwörter in Git.

4. Commands¶

Timesheets (Mitglieder)¶

!zeit YYYY-MM-DD hh:mm-hh:mm ; <tätigkeit> ; <ort> ; [notiz]
!dauer YYYY-MM-DD <minuten> ; <tätigkeit> ; <ort> ; [notiz]
!liste [n]
!delete <id>

Genehmigung (Approver)¶

!pending
!pending 25
!pending count
!pending YYYY-MM [n]
!approve <id> [; kommentar]
!reject <id> [; grund]
!approve-all [; YYYY-MM]

Auswertung¶

!meine-stunden [YYYY]

Admin¶

!admin role add @user:server role
!admin role remove @user:server role
!admin role list @user:server
!admin perms @user:server

Health¶

!health Funktioniert:
im Admin-Raum
im Direktchat mit Admins

5. Betrieb¶

Start / Stop / Logs¶

docker compose up -d
docker compose logs -f bot
docker compose restart bot
docker compose down

Status-Export¶

Pfad:

/var/lib/ghv-messenger-bot/exports/bot_status.json

Inhalt:

state: online | offline
since: UTC Timestamp
last_error: letzte Fehlermeldung (optional)

Beispiel:

{
  "state": "online",
  "since": "2026-01-06T17:12:12Z",
  "last_error": null
}

Stunden-Export¶

Pfad:

/var/lib/ghv-messenger-bot/exports/hours_2026.json

Beispiel:

{
  "year": 2026,
  "generated_at": "2026-01-06T17:12:12Z",
  "total_minutes": 90,
  "total_hours": 1.5,
  "pending_minutes": 0,
  "pending_hours": 0.0,
  "monthly_minutes": {
    "01": 90,
    "02": 0,
    "03": 0,
    "04": 0,
    "05": 0,
    "06": 0,
    "07": 0,
    "08": 0,
    "09": 0,
    "10": 0,
    "11": 0,
    "12": 0
  }
}

6. nginx / MkDocs Integration¶

Einzeldatei ausliefern (empfohlen)¶

location = /assets/data/hours_2026.json {
    default_type application/json;
    add_header Cache-Control "no-store";
    add_header X-Robots-Tag "noindex, nofollow";
    alias /var/lib/ghv-messenger-bot/exports/hours_2026.json;
}

Wichtig: alias nicht mit try_files kombinieren.

Rechte¶

nginx (www-data) muss lesen dürfen:

namei -l /var/lib/ghv-messenger-bot/exports/hours_2026.json

Parent-Verzeichnisse müssen mindestens x, Datei r haben.

7. Backups & Restore¶

Backups¶

täglich
Format: PostgreSQL .dump
Pfad: /var/backups/ghv-messenger-bot/

Restore (Kurzfassung)¶

docker compose stop bot
BACKUP="$(ls -1 /var/backups/ghv-messenger-bot/*.dump | tail -n 1)"
docker compose exec -T postgres pg_restore --clean --if-exists -d "$POSTGRES_DB" < "$BACKUP"
docker compose up -d bot

8. Troubleshooting¶

Bot reagiert nicht¶

Logs prüfen:

docker compose logs -f bot

bot_status.json prüfen
!health im Admin-Raum ausführen

Datenbank-Fehler¶

relation does not exist

docker compose run --rm bot migrate run --config /etc/ghv-messenger-bot/config.toml

role 'member' is missing¶

docker compose run --rm bot seed run --config /etc/ghv-messenger-bot/config.toml --admin <user>

nginx: Permission denied¶

namei -l /var/lib/ghv-messenger-bot/exports/hours_2026.json

JSON wird im Browser nicht aktualisiert¶

Browser-Cache leeren oder Hard Reload
nginx: Cache-Control: no-store prüfen

9. Testbetrieb – Definition¶

Der Testbetrieb gilt als erfolgreich, wenn:

Stunden erfasst werden können
Genehmigung funktioniert
hours_YYYY.json korrekt aktualisiert wird
bot_status.json zuverlässig online/offline abbildet
keine manuellen DB-Eingriffe nötig sind

Zuletzt aktualisiert: 13. Januar 2026