PKR-Lab

10010 - ntfy — Self-hosted Push-Notifications mit iOS-Support

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/1-benachrichtigungen/10010-ntfy.md

ntfy — Self-hosted Push-Notifications mit iOS-Support

ntfy ist ein einfacher, selbst gehosteter Pub/Sub-Notification-Dienst. Er unterstützt echte iOS-Push-Nachrichten über Apple Push Notification Service (APNs), indem es Nachrichten über das ntfy.sh-Relay weiterleitet.


Architektur

Alertmanager / beliebiger curl-Sender
        │
        ▼
ntfy-Server (https://ntfy-tech.pke-lab.de / https://ntfy.tech.homeserver)
        │
        ├── Android-App (direkt via WebSocket)
        │
        └── ntfy.sh-Relay ──► Apple APNs ──► iOS-App

Das upstream-base-url: https://ntfy.sh in der Konfiguration aktiviert diesen Relay. Die Nachrichteninhalte verlassen dabei deinen Server im Klartext in Richtung ntfy.sh — für sensible Daten ggf. End-to-End-Verschlüsselung aktivieren (siehe unten).


Deployment

ArgoCD deployt ntfy automatisch sobald der Branch auf main gemergt ist:

argocd/apps/tech/ntfy/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── configmap.yaml      # server.yml
    ├── deployment.yaml
    ├── ingress.yaml
    ├── pvc.yaml
    ├── service.yaml
    └── serviceaccount.yaml

URL nach dem Deployment (Domain-Tier tech, siehe
capulus-core/c-netzwerk-dns/c0040-domain-tiers.md):


base-url — Pflicht für iOS-Push-Inhalte

config.base-url (in argocd/apps/tech/ntfy/values.yaml) muss auf den
extern erreichbaren HTTPS-Host (https://ntfy-tech.pke-lab.de) zeigen,
nicht auf den internen .tech.homeserver-Host.

Grund: ntfy.sh liefert dem iPhone per APNs nur einen stillen "Wach
auf"-Push. Der eigentliche Nachrichteninhalt wird danach von der
Notification-Service-Extension der App per GET gegen ${base-url}/...
nachgeladen — und zwar auf dem Netz, in dem sich das Handy gerade
befindet (Mobilfunk, fremdes WLAN, ...), nicht zwingend im Heimnetz.

Zeigt base-url auf einen LAN-only-Hostnamen oder auf http:// statt
https://, schlägt dieser Nachlade-Request außerhalb des Heimnetzes fehl
(DNS unauflösbar bzw. von iOS' App Transport Security blockiert) — die
Push-Benachrichtigung kommt zwar an (Sperrbildschirm zeigt einen
Platzhalter), aber ohne Inhalt, und die Nachricht taucht auch beim
Öffnen der App nicht auf. Passiert am 2026-09-15 real: base-url stand
auf http://ntfy.tech.homeserver, obwohl ntfy-tech.pke-lab.de als
öffentlicher Host bereits existierte.


iOS einrichten

  1. ntfy-App aus dem App Store installieren
  2. App öffnen → + → Server-URL eintragen: https://ntfy-tech.pke-lab.de
  3. Topic abonnieren, z.B. Home-Lab
  4. Benachrichtigungen in den iOS-Einstellungen für ntfy erlauben

Hinweis: Die Topics sind nicht öffentlich. Die App braucht den Benutzer reader (Authentifizierung und Zugangsdaten).


Nachrichten senden

Einfachste Form

curl -d "Hallo Welt" https://ntfy-tech.pke-lab.de/Home-Lab

Mit Titel und Priorität

curl \
  -H "Title: Home-Server Alert" \
  -H "Priority: high" \
  -H "Tags: warning" \
  -d "Festplatte > 90% voll" \
  https://ntfy-tech.pke-lab.de/Home-Lab

Prioritäten

Wert Bedeutung
min / 1 Stumm
low / 2 Leise
default / 3 Normal
high / 4 Laut
urgent / 5 Dringend, DND wird ignoriert

Tags (Emoji-Icons in der App)

-H "Tags: white_check_mark"   # 
-H "Tags: warning"             # 
-H "Tags: rotating_light"      # 

Vollständige Emoji-Liste: https://docs.ntfy.sh/emojis/


DNS

Kein manueller dnsmasq-Eintrag nötig: dnsmasq (address=/homeserver/<ip>)
und der CoreDNS-Forward im Cluster matchen bereits die komplette
homeserver-Zone inkl. aller Subdomains, ntfy.tech.homeserver löst also
automatisch mit auf, siehe
capulus-core/c-netzwerk-dns/c0040-domain-tiers.md.
Der externe Host ntfy-tech.pke-lab.de läuft über die
Cloudflare-Tunnel-Wildcard-Regel für *.pke-lab.de — ebenfalls kein
App-spezifischer DNS-Eintrag nötig.


Authentifizierung und Zugangsdaten

ntfy kennt zwei Nutzer ohne Admin-Rolle. Verwaltet wird über die CLI im Pod (kubectl -n ntfy exec deploy/ntfy -- ntfy …), die direkt auf auth.db im Daten-PVC arbeitet. Ein Web-Admin ist nicht angelegt.

Nutzer Rechte Verwendet von
publisher write-only auf Home-Lab*, Alarmmonitor, instagram, isc-news, isc-urkunden, whatsapp-relay, zammad* ntfy-bridge, alamos-apager (je Token als SealedSecret), n8n (Credential „ntfy-publisher“), Host-Skripte (Datei /etc/ntfy-publisher/auth-header)
reader read-only auf dieselben Topics carplay-api (Token als SealedSecret), iOS-ntfy-App und Uptime Kuma (Benutzername und Passwort)

Der Default auth-default-access steht im Chart auf deny-all. Ohne Token oder Login lehnt ntfy jedes Lesen und Schreiben mit 401 oder 403 ab, auch Aufrufe aus dem Cluster. Ein neuer Sender oder Leser braucht deshalb zuerst einen Token, sonst verstummt seine Meldung still. Für eine Notfall-Rückkehr genügt read-write in argocd/apps/tech/ntfy/values.yaml, die Nutzer und Tokens bleiben in auth.db erhalten.

Wer sendet wie

Sender Wo steht der Token
ntfy-bridge (Home-Lab) SealedSecret ntfy-bridge-ntfy-token, Env NTFY_TOKEN
alamos-apager (Alarmmonitor) SealedSecret alamos-apager-ntfy-token, Env NTFY_TOKEN
carplay-api (liest Home-Lab, Home-Lab-System) SealedSecret carplay-api-ntfy-token, Env NTFY_TOKEN
n8n (11 HTTP-Nodes in vier Workflows) n8n-Credential „ntfy-publisher“ (Typ Header Auth), liegt in der n8n-Datenbank, nicht im Repo
thermal-watchdog, resource-watchdog, cluster-power-manager, nightly-worker-wake Datei /etc/ntfy-publisher/auth-header (Modus 0600), geschrieben von der Rolle ntfy_publisher aus der Vault-Variable ntfy_publisher_token

Einrichten (Erstanlage)

Die Zugangsdaten werden einmal erzeugt und in eine Datei mit Modus 0600 außerhalb des Repos geschrieben (~/ntfy-credentials-2026-10-17.txt). Dort liegen die beiden Passwörter und beide Tokens. Danach in den Passwortmanager übernehmen und die Datei löschen.

scripts/seal-ntfy-tokens.sh
ansible-vault edit group_vars/all.yml
ansible-playbook -i inventory/hosts.yml site.yml --tags ntfy-publisher,thermal,power-management --ask-vault-pass
ansible-playbook -i inventory/hosts.yml controlplane-1.yml --tags ntfy-publisher,thermal --ask-vault-pass
ansible-playbook -i inventory/hosts.yml worker-1.yml --tags ntfy-publisher,thermal --ask-vault-pass
ansible-playbook -i inventory/hosts.yml banana-pi-kiosks.yml --tags ntfy-publisher,thermal --ask-vault-pass
ansible-playbook -i inventory/hosts.yml xibo-kiosks.yml --tags ntfy-publisher,thermal --ask-vault-pass

scripts/seal-ntfy-tokens.sh liest die Tokens aus der Datei, versiegelt sie je Namespace und trägt sie in die values.yaml von ntfy-bridge, alamos-apager und carplay-api ein (enabled: true). In den Vault kommt ntfy_publisher_token (der publisher_token). Die Playbooks mit der Rolle ntfy_publisher verteilen ihn auf homeserver, worker-0, worker-1 und die Kiosk-Pis.

Zugangsdaten und Token-Rotation

  1. Neuen Token anlegen, alten noch nicht löschen: kubectl -n ntfy exec deploy/ntfy -- ntfy token add --label='publisher <Datum>' publisher.
  2. Neuen Wert in die Credentials-Datei übernehmen, scripts/seal-ntfy-tokens.sh ausführen, ntfy_publisher_token im Vault ersetzen und das n8n-Credential „ntfy-publisher“ aktualisieren.
  3. Nach dem Rollout (ArgoCD sync, Ansible-Lauf) prüfen, dass jeder Sender noch ankommt, dann den alten Token entfernen: ntfy token remove publisher <alter Token>.
  4. Eintrag in ops/token-register.yaml (issued) aktualisieren.

Ist auth.db verloren (PVC-Verlust), sind alle Nutzer und Tokens weg und mit deny-all kommt keine Meldung mehr an. Dann Nutzer und Tokens neu anlegen und neu verteilen, oder für die Zwischenzeit auth-default-access zurück auf read-write stellen. Ein Backup der Datei gehört zu jeder Änderung: kubectl -n ntfy exec deploy/ntfy -- cat /var/lib/ntfy/auth.db > auth.db.bak.

iOS-App und Uptime Kuma

Prüfen

curl -s -o /dev/null -w '%{http_code}\n' -d 'audit-test' https://ntfy-tech.pke-lab.de/audit-test
curl -s -o /dev/null -w '%{http_code}\n' 'https://ntfy-tech.pke-lab.de/Home-Lab/json?poll=1'
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $PUBLISHER_TOKEN" -d 'test' https://ntfy-tech.pke-lab.de/Home-Lab

Ohne Token müssen die ersten beiden 401 oder 403 liefern, mit dem Publisher-Token muss das Senden 200 ergeben. Ein Test-Alarm (kubectl -n monitoring exec … amtool alert add) muss bis zur iOS-App durchlaufen.


End-to-End-Verschlüsselung (optional)

Wenn Nachrichten über ntfy.sh-Relay nicht im Klartext weitergeleitet werden sollen:

# Lokal verschlüsseln (ntfy CLI)
ntfy publish --password "geheim" https://ntfy-tech.pke-lab.de/Home-Lab "Meine Nachricht"

In der iOS-App: Topic-Einstellungen → Passwort eintragen.


Troubleshooting

Pod startet nicht

kubectl -n ntfy get pods
kubectl -n ntfy logs deploy/ntfy

Push kommt an, aber ohne Inhalt / nichts in der App (obwohl Server aktiv publiziert)

Das ist praktisch immer ein falsches base-url, siehe
base-url — Pflicht für iOS-Push-Inhalte
oben. Prüfen:

kubectl -n ntfy get configmap ntfy-config -o jsonpath='{.data.server\.yml}'

Muss base-url: "https://ntfy-tech.pke-lab.de" enthalten — jede andere URL
(intern, http://) bricht das Nachladen der Nachricht durch die iOS-App.
Nach einer Korrektur: kubectl -n ntfy rollout restart deploy/ntfy.

Ob tatsächlich publiziert wird, zeigen die Server-Stats im Log
(messages_published, messages_cached):

kubectl -n ntfy logs deploy/ntfy --tail=5

iOS-Benachrichtigungen kommen gar nicht an

  1. Prüfen ob upstream-base-url: https://ntfy.sh in der ConfigMap gesetzt ist:
    kubectl -n ntfy get configmap ntfy-config -o yaml
    
  2. Prüfen ob der Pod Internetzugang hat (ntfy.sh muss erreichbar sein):
    kubectl -n ntfy exec deploy/ntfy -- wget -q -O- https://ntfy.sh/v1/health
    
  3. iOS-Benachrichtigungen in Einstellungen → ntfy → Mitteilungen prüfen

Nachrichten testen

# Direkt vom Cluster aus
kubectl -n ntfy exec deploy/ntfy -- \
  wget -q -O- --post-data="Test von kubectl" http://localhost:8080/test