ntfy¶

ntfy ist ein selbst-gehosteter Push-Notification-Server. Alle Homelab-Services (Uptime Kuma, Healthchecks, Borgmatic, Alertmanager etc.) senden Benachrichtigungen ueber diese Instanz ans Smartphone.

Zugang¶

Parameter	Wert
URL	`https://ntfy.homelab-external.robinwerner.net`
Port (intern)	80
Netzwerk	`proxy`

Container-Konfiguration¶

Parameter	Wert
Image	`binwiederhier/ntfy:v2.17.0`
Container-Name	`ntfy`
Neustart	`unless-stopped`
Netzwerk	`proxy`
Startbefehl	`serve`

Volumes:

Quelle	Ziel	Beschreibung
`/opt/homelab-data/ntfy/cache`	`/var/cache/ntfy`	Nachrichten-Cache
`/opt/homelab-data/ntfy/data`	`/var/lib/ntfy`	Auth-DB, Attachment-Cache

Umgebungsvariablen:

Variable	Wert	Beschreibung
`TZ`	`Europe/Berlin`	Zeitzone
`NTFY_BASE_URL`	`https://ntfy.homelab-external.robinwerner.net`	Oeffentliche Basis-URL
`NTFY_UPSTREAM_BASE_URL`	`https://ntfy.sh`	Upstream fuer UnifiedPush-Weiterleitung
`NTFY_AUTH_DEFAULT_ACCESS`	`deny-all`	Standardmaessig kein Zugriff ohne Login
`NTFY_CACHE_FILE`	`/var/lib/ntfy/cache.db`	SQLite-Cache fuer Nachrichten
`NTFY_AUTH_FILE`	`/var/lib/ntfy/auth.db`	SQLite-Datenbank fuer Benutzer
`NTFY_ATTACHMENT_CACHE_DIR`	`/var/lib/ntfy/attachments`	Verzeichnis fuer Anhaenge
`NTFY_BEHIND_PROXY`	`true`	Traefik als vorgelagerter Proxy
`NTFY_ENABLE_LOGIN`	`true`	Web-UI-Login aktiviert

DNS-Konfiguration:

dns:
  - 10.10.10.3   # Pi-hole (primaer)
  - 1.1.1.1      # Cloudflare (Fallback)

Netzwerk¶

ntfy ist nur im proxy-Netzwerk und kommuniziert nicht mit internen Diensten.

Traefik-Routing:

ntfy.homelab-external.robinwerner.net → ntfy:80

Middlewares: security-headers (HSTS, X-Frame-Options, Referrer-Policy, Permissions-Policy)

Wichtige Konfiguration¶

Zugriffssteuerung¶

NTFY_AUTH_DEFAULT_ACCESS=deny-all bedeutet: Jede Aktion (Lesen, Schreiben) erfordert Authentifizierung. Topics sind nicht oeffentlich lesbar oder beschreibbar.

Benutzer und Topic-Berechtigungen werden ueber die CLI oder Web-UI verwaltet.

UnifiedPush¶

NTFY_UPSTREAM_BASE_URL ermoeglicht UnifiedPush-Kompatibilitaet: Apps die ntfy.sh als Upstream verwenden, koennen stattdessen diese Instanz nutzen.

Nachrichtenformat (Beispiel)¶

# Einfache Nachricht
curl -u user:pass -d "Backup abgeschlossen" \
  https://ntfy.homelab-external.robinwerner.net/homelab-alerts

# Mit Prioritaet und Tags
curl -u user:pass \
  -H "Title: Disk voll" \
  -H "Priority: urgent" \
  -H "Tags: warning,disk" \
  -d "NAS-Disk > 90%" \
  https://ntfy.homelab-external.robinwerner.net/homelab-alerts

Wartung¶

Ersteinrichtung¶

# Admin-Benutzer anlegen
docker exec -it ntfy ntfy user add --role=admin admin
# Passwort wird interaktiv abgefragt

Weitere Benutzer und Berechtigungen¶

# Benutzer anlegen
docker exec ntfy ntfy user add <username>

# Schreibzugriff auf Topic geben
docker exec ntfy ntfy access <username> homelab-alerts rw

# Nur Lesezugriff
docker exec ntfy ntfy access <username> homelab-alerts ro

# Alle Benutzer auflisten
docker exec ntfy ntfy user list

Logs¶

docker compose logs -f ntfy

Healthcheck¶

Der Healthcheck prueft /v1/health auf "healthy": true:

curl -s https://ntfy.homelab-external.robinwerner.net/v1/health

Backup¶

Persistente Daten in /opt/homelab-data/ntfy/. Die Auth-DB und der Nachrichten-Cache liegen unter /opt/homelab-data/ntfy/data/.

Update¶

Images sind auf konkrete Versionen gepinnt. Renovate erstellt woechtentlich PRs fuer Updates. Nach Merge auf main wird der Stack automatisch per Cron-Job (dienstags 12:00 UTC) aktualisiert.

# Manuelles Update
cd /opt/homelab-repo/hetzner
docker compose pull ntfy
docker compose up -d ntfy