docu/migration/nextcloud-notify-push-freigabe.md

Freigabe: notify_push (Client Push / Rust HPB)

Status: ⏳ Zur Absegnung — noch nicht umgesetzt
Erstellt: 2026-06-28
Betrifft: VM 101 ubuntu · Container nextcloud · NPM · kein NC-Version-Upgrade

Dieses Dokument beschreibt den geplanten Rollout von notify_push (High Performance Backend für Files, Rust-Daemon). Ziel: weniger Client-Polling (index.php/204, status.php) → weniger PHP-FPM-Last.

Voraussetzungen (bereits erfüllt):

Voraussetzung	Status
Redis in config.php	✅
PHP-FPM Tuning (12 Worker)	✅ (2026-06-28)
VM RAM 12 GB	✅
Nginx /push/-Block im Nextcloud-Container	✅ bereits in default.conf
NPM WebSocket-Header für cloud.jeanavril.com	✅ bereits aktiv

---

Kurzfassung

Was	Empfehlung
Deploy-Methode	Linuxserver Docker Mod (nicht separater Sidecar)
Compose-Änderung	1 Zeile: DOCKER_MODS=linuxserver/mods:nextcloud-notify-push
NPM-Änderung	Keine — /push/ wird im Nextcloud-Container terminiert
App	notify_push v1.3.3 (NC 34 kompatibel)
Erwarteter Effekt	Deutlich weniger Polling-Requests in Nginx-Logs

---

Warum notify_push?

Problem heute: Desktop- und Mobile-Clients fragen regelmäßig den Server ab, ob sich Dateien geändert haben (GET /index.php/204, GET /status.php). Das erzeugt dauerhaft PHP-FPM-Last — unabhängig von der Client-Version.

Lösung: Der Rust-Daemon hält WebSocket-Verbindungen offen und pusht Änderungen an Clients. Clients pollen seltener (best-effort, Polling bleibt als Fallback).

Relevanz für euren Incident (28.06.2026): v1.3.3 enthält Fixes gegen DB-Query-Spitzen bei Cache-Invalidierung — passt zum beobachteten Lastmuster.

Quellen:

• https://github.com/nextcloud/notify_push
• https://apps.nextcloud.com/apps/notify_push (v1.3.3 für NC 34)
• https://nextcloud.com/blog/… (ADA/HPB Files v2 Kontext)

---

Architektur nach Umsetzung

Client (Desktop/Android)
    │  wss://cloud.jeanavril.com/push/…
    ▼
NPM (10.2.2.254)          ← TLS, WebSocket-Upgrade (bereits konfiguriert)
    │  http://10.2.2.253:80
    ▼
Nextcloud-Container (10.2.2.253)
    ├── Nginx  location ^~ /push/  → 127.0.0.1:7867
    └── notify_push (Rust)         ← via Docker Mod, Port 7867 intern
    │
    ├── Redis (nextcloud-redis-1)  ← Pub/Sub
    └── MariaDB (nextcloud-db-1)

Kein neuer externer Port. Der Push-Daemon läuft im Nextcloud-Container (Mod), nicht als separater öffentlicher Dienst.

---

Empfohlene Methode: Linuxserver Docker Mod

Ihr nutzt lscr.io/linuxserver/nextcloud:latest. Linuxserver bietet dafür einen offiziellen Mod an — der passt besser als ein separater Sidecar-Container:

	Docker Mod (empfohlen)	Separater Sidecar
Wartung	offiziell von Linuxserver	manuell (Binary-Version, Netzwerk)
Nginx /push/	bereits in default.conf	NPM Custom Location nötig
trusted_proxies-Probleme	selten (Push lokal im Container)	häufig (GitHub #663)
Compose-Änderung	1 Env-Variable	neuer Service + Netzwerk

Mod-Doku: https://github.com/linuxserver/docker-mods/tree/nextcloud-notify-push

---

Geplante Änderungen (Detail)

1. /opt/stacks/nextcloud/compose.yml

Nur beim Service nextcloud unter environment ergänzen:

  nextcloud:
    # … bestehende Einträge …
    environment:
      - PUID=33
      - PGID=33
      - TZ=Etc/UTC
      - DOCKER_MODS=linuxserver/mods:nextcloud-notify-push   # NEU

Nicht ändern: db, redis, collabora, Volumes, Netzwerke, Image-Tag.

2. Container neu erstellen (nur nextcloud)

cd /opt/stacks/nextcloud
docker compose pull nextcloud
docker compose up -d --force-recreate nextcloud

Hinweis: Wie beim PHP-FPM-Tuning reicht docker restart nicht — Mod wird beim Container-Erstellen geladen.

Erwartete Unterbrechung: ~10–30 s für Nextcloud (Clients reconnecten automatisch).

3. App installieren & aktivieren

docker exec -u abc nextcloud php /app/www/public/occ app:install notify_push
docker exec -u abc nextcloud php /app/www/public/occ app:enable notify_push

(Falls App-Store nicht erreichbar: manuell v1.3.3 von https://apps.nextcloud.com/apps/notify_push)

4. Setup-Wizard

docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push

Der Wizard prüft automatisch: Erreichbarkeit, WebSocket, Reverse Proxy, Redis.

5. Logs prüfen

docker logs nextcloud 2>&1 | grep -i notify
# Erwartet: "**** Starting notify-push ****"

---

NPM — bewusst keine Änderung

Aktueller Stand (/opt/stacks/npm/data/nginx/proxy_host/1.conf):

• Forward: http://10.2.2.253:80
• WebSocket-Header: bereits gesetzt (Upgrade, Connection, http/1.1)
• Kein separater Custom Location /push nötig

Der /push/-Pfad wird vom internen Nginx im Nextcloud-Container an den Mod-Daemon weitergeleitet (Block existiert bereits):

location ^~ /push/ {
    proxy_pass http://127.0.0.1:7867/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

---

Bekannte Stolpersteine & Fallbacks

„push server is not a trusted proxy“

trusted_proxies in config.php enthält bereits:

• 10.1.1.1
• 10.2.2.254 (NPM)

Falls notify_push:setup den Test dennoch fehlschlägt:

1. IP aus der Fehlermeldung in trusted_proxies aufnehmen (oft 127.0.0.1 bei Mod-Setup)
2. Per occ (Beispiel — exakte IP aus Setup-Output nehmen):

docker exec -u abc nextcloud php /app/www/public/occ config:system:set trusted_proxies 2 --value=127.0.0.1

3. Setup erneut ausführen

Quelle: https://github.com/nextcloud/notify_push#push-server-is-not-a-trusted-proxy

Mod startet nicht

• Redis erreichbar? (docker exec nextcloud-redis-1 redis-cli ping)
• Container-Log auf Fehler prüfen
• ggf. default.conf neu generieren (nur wenn /push/-Block fehlt):

# Nur wenn Block fehlt — bei uns vorhanden, normalerweise NICHT nötig:
mv /opt/stacks/nextcloud/config/nginx/site-confs/default.conf /opt/stacks/nextcloud/config/nginx/site-confs/default.conf.bak
docker compose up -d --force-recreate nextcloud

App-Store nicht erreichbar

Bekanntes Log-Thema (Timeout zu apps.nextcloud.com). App kann manuell installiert werden — kein Blocker für notify_push selbst.

---

Was bewusst NICHT geändert wird

Item	Grund
config.php Redis-Einträge	bereits korrekt
Separates Redis für notify_push_redis	optional, Phase 2 — erst bei Last-Problemen
NPM Compose / Custom Locations	nicht nötig mit Mod
NC Minor-Update 34.0.1	separater Schritt
Desktop-Client-Updates	optional, nicht Voraussetzung

---

Risiken

Risiko	Einschätzung	Mitigation
Kurze Cloud-Unterbrechung beim Recreate	gering	bei wenig Traffic umsetzen
Mod-Inkompatibilität nach Image-Update	mittel	Image-Tag pinnen (separates TODO)
Setup schlägt fehl (trusted_proxy)	mittel	Fallbacks oben
Mehr RAM im Nextcloud-Container	gering	~20–50 MB für Rust-Daemon; VM hat 12 GB
Rollback nötig	gering	siehe unten

---

Rollback

1. DOCKER_MODS-Zeile aus compose.yml entfernen
2. docker compose up -d --force-recreate nextcloud
3. App deaktivieren: occ app:disable notify_push
4. Optional App deinstallieren: occ app:remove notify_push

Kein DB-Rollback nötig. Keine NPM-Änderungen rückgängig zu machen.

---

Verifikation nach Umsetzung

# 1. Daemon läuft
docker logs nextcloud 2>&1 | grep -i "notify-push"

# 2. Setup OK
docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push

# 3. Metriken (nach Client-Verbindung)
docker exec -u abc nextcloud php /app/www/public/occ notify_push:metrics

# 4. Polling zurückgegangen? (24h beobachten)
docker exec nextcloud tail -f /config/log/nginx/access.log | grep -E 'status\.php|index\.php/204'

Erfolgskriterien:

• notify_push:setup ohne Fehler
• Log: „Starting notify-push“
• notify_push:metrics zeigt Verbindungen (sobald Clients online)
• Weniger index.php/204 / status.php in Access-Log vs. vorher
• Kein erneuter PHP-FPM-Auslastungs-Incident unter Normal-Last

---

Empfohlene Reihenfolge

Schritt	Aktion	Dauer
A	Optional: VM-Snapshot pre-notify-push	1 min
B	compose.yml: DOCKER_MODS ergänzen	1 min
C	docker compose up -d --force-recreate nextcloud	~30 s
D	Log: Mod gestartet?	1 min
E	App installieren + enable	2 min
F	notify_push:setup https://cloud.jeanavril.com/push	2 min
G	Bei Fehler: trusted_proxies anpassen	ggf.
H	Metriken + Access-Log 24h beobachten	laufend

Optional vorher: VM-Snapshot auf pve1 (qm snapshot 101 pre-notify-push-YYYYMMDD).

---

Umsetzungs-Befehle (nach Freigabe)

# Auf VM 101 (als jean mit sudo) oder via SSH

# A) compose.yml editieren — DOCKER_MODS Zeile hinzufügen (siehe oben)

# B) Deploy
cd /opt/stacks/nextcloud
sudo docker compose pull nextcloud
sudo docker compose up -d --force-recreate nextcloud
sleep 15
sudo docker logs nextcloud 2>&1 | tail -30

# C) App + Setup
sudo docker exec -u abc nextcloud php /app/www/public/occ app:install notify_push
sudo docker exec -u abc nextcloud php /app/www/public/occ app:enable notify_push
sudo docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push

# D) Metriken
sudo docker exec -u abc nextcloud php /app/www/public/occ notify_push:metrics

---

Alternative (nicht empfohlen): Separater Sidecar-Container

Falls der Docker Mod Probleme macht, wäre ein separater Container mit ghcr.io/nextcloud/notify_push möglich — erfordert dann:

• neuen Service in compose.yml mit DATABASE_URL, REDIS_URL, NEXTCLOUD_URL
• NPM Custom Location /push → Sidecar-IP:7867
• trusted_proxies für Sidecar-Subnetz
• Netzwerk-Anbindung an nextcloud_default + ggf. docbr0

Für euren Stack nicht empfohlen — Mod ist der offizielle Linuxserver-Weg und vermeidet die meisten Proxy-Probleme.

---

Freigabe

☐	Freigegeben — Docker Mod wie beschrieben umsetzen
☐	Anpassung — z. B. Sidecar statt Mod, oder erst Snapshot
☐	Abgelehnt / später

Freigegeben von: _______________
Datum: _______________
Anmerkungen: _______________

---

Referenzen

Thema	URL
notify_push GitHub	https://github.com/nextcloud/notify_push
Linuxserver Mod	https://github.com/linuxserver/docker-mods/tree/nextcloud-notify-push
App Store v1.3.3	https://apps.nextcloud.com/apps/notify_push
trusted_proxies Troubleshooting	https://github.com/nextcloud/notify_push#push-server-is-not-a-trusted-proxy
Bereits umgesetztes Tuning	nextcloud-tuning-freigabe.md
Gesamt-Roadmap	nextcloud-optimierung-und-updates.md