ntfy2vikunja

Vikunja ist obsolet. Das Projekt wurde eingestellt; es wird nur noch Nextcloud Deck als Backend unterstützt. Die Vikunja-Option bleibt aus Abwärtskompatibilität im Code, wird aber nicht mehr gepflegt.

Bridge von ntfy nach Nextcloud Deck (früher auch Vikunja):

• Nachrichten werden per WebSocket von NTFY_TOPIC gelesen
• in einer lokalen SQLite-Queue zwischengespeichert
• vom Worker zuverlässig als Tasks (Vikunja) oder Karten (Deck) angelegt

Verwende BACKEND=deck (Standard). BACKEND=vikunja ist obsolet und wird nicht mehr gepflegt.

Features

• WebSocket-Subscriber (ntfy)
• Persistente Queue (SQLite)
• Retry mit Exponential Backoff
• Dead-letter Zustand (dead) nach zu vielen Fehlversuchen
• Entkoppelte Architektur (Ingestor/Worker) oder kombinierter Runner

Tests

Vor Aenderungen oder neuen Features: Tests ausfuehren, damit bestehende Funktionalitaet erhalten bleibt.

pip install -r requirements-dev.txt
pytest tests/ -v --cov=queue_store --cov=bridge_worker --cov=bridge_ingestor --cov=vikunja_lookup --cov=create_task --cov=deck_client

Die CI laeuft Tests vor jedem Deploy; der Deploy wird blockiert, wenn Tests fehlschlagen.

Security-Checks: pip-audit und bandit -r . -x ./tests

Projektstruktur

• ntfy_subscribe.py – WebSocket-Client für ntfy
• create_task.py – Vikunja Task-Erstellung (bei BACKEND=vikunja)
• vikunja_lookup.py – Projekt- und Bucket-Namen in IDs auflösen
• deck_client.py – Nextcloud Deck API (Karten anlegen, Board/Stack auflösen; bei BACKEND=deck)
• queue_store.py – SQLite Queue-Layer
• bridge_ingestor.py – ntfy -> Queue
• bridge_worker.py – Queue -> Vikunja oder Deck (je nach BACKEND)
• bridge_run.py – Ingestor + Worker in einem Prozess (lokal/dev)
• healthcheck.py – Queue-Status als JSON (Monitoring)
• deploy/systemd/*.service – Linux Services
• .forgejo/workflows/deploy.yml – Forgejo CI/CD Deploy Workflow

Voraussetzungen

• Python 3.11+ (3.10 sollte ebenfalls funktionieren)
• Abhängigkeiten aus requirements.txt

Installation:

pip install -r requirements.txt

Konfiguration

Als Vorlage:

cp .env.example .env

Relevante ENV-Variablen:

• BACKEND – deck (Standard; Vikunja ist obsolet)
• NTFY_BASE_URL, NTFY_TOPIC, NTFY_TOKEN (oder NTFY_USER/NTFY_PASSWORD)
• NTFY_FEEDBACK_TOPIC (optional: sendet "Task erstellt" als ntfy-Message)
• NTFY_FEEDBACK_BASE_URL / NTFY_FEEDBACK_TOKEN (optional)
• DUE_TIME (optional, Standard 10:00) – Tageszeit für Fälligkeitsdatum, wenn nur Datum angegeben wird (HH:MM oder HH:MM:SS, UTC)
• QUEUE_DB_PATH (z. B. ./state/queue.db oder /opt/ntfy2vikunja/state/queue.db)

Bei BACKEND=deck (Standard):

• NEXTCLOUD_URL (z. B. https://nextcloud.example.com)
• NEXTCLOUD_USER, NEXTCLOUD_PASSWORD (oder App-Passwort)
• DECK_BOARD – Board-ID oder Name
• DECK_STACK – Stack-ID oder Name (Spalte, z. B. ToDo)
• DECK_STACK_HIGH_PRIO (optional: Stack fuer Nachrichten mit fuehrendem ! ohne due:)

Bei BACKEND=vikunja (obsolet, nicht mehr gepflegt):

• VIKUNJA_URL, VIKUNJA_TOKEN, VIKUNJA_PROJECT, VIKUNJA_BUCKET_HIGH_PRIO

Lokal starten

Option A: Alles in einem Prozess

python bridge_run.py

Option B: Getrennt starten

Terminal 1:

python bridge_ingestor.py

Terminal 2:

python bridge_worker.py

Task-Mapping (aktuell)

• title: erste Zeile von message, sonst ntfy title
• priority: Parsing aus prio:/priority: oder fuehrendem ! in Title/Body
• due_date: optional aus Title oder Body via Pattern due:YYYY-MM-DD
• Android-Leer-Events wie triggered (ohne Inhalt) werden ignoriert

Beispiel:

Server reboot prio:high due:2026-03-01

Beispiele Nachricht -> Task

• Backup pruefen -> Task ohne due_date, ohne priority
• Backup pruefen due:2026-03-10 -> Task mit due_date=2026-03-10
• Backup pruefen prio:5 -> Task mit priority=5
• Backup pruefen prio:high due:2026-03-10 -> Task mit priority=4, due_date=2026-03-10
• ! Backup sofort pruefen due:2026-03-10 -> Task mit priority=5, due_date=2026-03-10
• ! Backup sofort (ohne due:) -> Task mit priority=5, due_date = Erstellungstag (heute); führendes ! wird aus dem Titel entfernt

Optional: Mit DECK_STACK_HIGH_PRIO landen Tasks mit fuehrendem ! (ohne due:) im angegebenen Stack (z. B. „Heute“). Normale Tasks landen in DECK_STACK (z. B. Inbox). Tasks mit Fälligkeitsdatum landen stets in der normalen Spalte.

Prioritaetsreihenfolge:

1. prio: / priority: Marker
2. fuehrender ! Marker (setzt priority=5)

Healthcheck

python healthcheck.py

Exit-Codes:

• 0: OK
• 1: Queue erreichbar, aber Schwellwert überschritten (z. B. zu viele dead)
• 2: Queue DB nicht gefunden

Queue-Zustände

• pending – neu
• processing – gerade in Bearbeitung
• failed – fehlgeschlagen, wird später erneut versucht
• done – erfolgreich in Deck erstellt
• dead – maximale Retry-Anzahl erreicht

Linux / systemd / Forgejo

Siehe:

• DEPLOY.md
• OPERATIONS.md
• deploy/systemd/ntfy2vikunja-ingestor.service
• deploy/systemd/ntfy2vikunja-worker.service
• deploy/systemd/ntfy2vikunja-bridge-run.service

Hinweise

• Für Produktion sind zwei getrennte Services (Ingestor + Worker) empfohlen.
• bridge_run.service ist praktisch, aber weniger isoliert.