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):
- Intern (LAN/Tailscale): https://ntfy.tech.homeserver
- Extern (Cloudflare-Tunnel): https://ntfy-tech.pke-lab.de
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
- ntfy-App aus dem App Store installieren
- App öffnen → + → Server-URL eintragen:
https://ntfy-tech.pke-lab.de - Topic abonnieren, z.B.
Home-Lab - 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
- Neuen Token anlegen, alten noch nicht löschen:
kubectl -n ntfy exec deploy/ntfy -- ntfy token add --label='publisher <Datum>' publisher. - Neuen Wert in die Credentials-Datei übernehmen,
scripts/seal-ntfy-tokens.shausführen,ntfy_publisher_tokenim Vault ersetzen und das n8n-Credential „ntfy-publisher“ aktualisieren. - 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>. - 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
- iOS-ntfy-App: Einstellungen → Benutzer verwalten → Benutzer
readermit Passwort fürhttps://ntfy-tech.pke-lab.deeintragen. Abos aufHome-Lab,Home-Lab-System,Alarmmonitorund die Workflow-Topics bleiben. - Uptime Kuma: Benachrichtigung „ntfy“ bearbeiten, Authentifizierung auf Benutzername und Passwort (
publisher) stellen. Für den Test „Test“ in der Benachrichtigung drücken.
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
- Prüfen ob
upstream-base-url: https://ntfy.shin der ConfigMap gesetzt ist:kubectl -n ntfy get configmap ntfy-config -o yaml - 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 - 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