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

Freigabe: notify_push (Client Push / Rust HPB)

Status: ✅ Umgesetzt (2026-06-28) — Sidecar statt Docker Mod (Mod scheiterte an fehlendem Container-Internet)
Erstellt: 2026-06-28
Betrifft: VM 101 ubuntu · Container nextcloud + nextcloud-notify-push · 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	Umsetzung
Deploy-Methode	Sidecar ghcr.io/nextcloud/notify_push:latest mit network_mode: service:nextcloud
Compose-Änderung	Neuer Service notify_push (Docker Mod nicht nutzbar — siehe unten)
NPM-Änderung	Keine — /push/ wird im Nextcloud-Container terminiert
App	notify_push v1.3.3 manuell in apps/ (App Store aus Container nicht erreichbar)
trusted_proxies	127.0.0.1 ergänzt (Index 3)
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 (Sidecar)      ← `network_mode: service:nextcloud`, 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.

---

Geplante Methode vs. tatsächliche Umsetzung

Geplant war: Linuxserver Docker Mod (DOCKER_MODS=linuxserver/mods:nextcloud-notify-push).

Ergebnis beim Test: Mod blieb bei [mod-init] Running Docker Modification Logic hängen — der Nextcloud-Container hatte kein ausgehendes Internet. Ursache: iptables: false in Docker (absichtlich für docbr0-Fest-IPs) ohne manuelles NAT. Behoben 2026-06-28 via docker-nat-rules.service auf VM 101. Mod zurückgenommen, Sidecar deployed (Sidecar bleibt produktiv).

	Docker Mod (geplant)	Sidecar (umgesetzt)
Wartung	offiziell von Linuxserver	Image ghcr.io/nextcloud/notify_push
Nginx /push/	bereits in default.conf	gleich — kein NPM nötig
trusted_proxies	selten nötig	127.0.0.1 ergänzt
Compose	1 Env-Variable	eigener Service + network_mode: service:nextcloud

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

---

Umgesetzte Änderungen (Detail)

1. /opt/stacks/nextcloud/compose.yml — Sidecar-Service

  notify_push:
    logging: *default-logging
    image: ghcr.io/nextcloud/notify_push:latest
    container_name: nextcloud-notify-push
    restart: unless-stopped
    network_mode: "service:nextcloud"
    depends_on:
      - nextcloud
    volumes:
      - ./config/www/nextcloud/config/config.php:/config/config.php:ro
    command: ["/notify_push", "--port", "7867", "--nextcloud-url", "http://127.0.0.1", "/config/config.php"]

network_mode: service:nextcloud teilt den Netzwerk-Namespace — Daemon lauscht auf 127.0.0.1:7867, Nginx /push/ funktioniert ohne NPM-Änderung.

--nextcloud-url http://127.0.0.1 umgeht TLS-Fehler beim internen Self-Test (CaUsedAsEndEntity gegen https://cloud.jeanavril.com).

2. Sidecar starten

cd /opt/stacks/nextcloud
sudo docker compose up -d notify_push

3. App manuell installieren (App Store aus Container nicht erreichbar)

# GitHub-Tarball v1.3.3 auf Host mit Internet laden, nach VM kopieren:
curl -sL "https://api.github.com/repos/nextcloud/notify_push/tarball/v1.3.3" -o /tmp/notify_push-src.tar.gz
# Entpacken nach /opt/stacks/nextcloud/config/www/nextcloud/apps/notify_push
# (custom_apps wurde vom Scanner nicht erkannt — apps/ nutzen)
sudo chown -R www-data:www-data .../apps/notify_push
sudo docker exec -u abc nextcloud php /app/www/public/occ app:enable notify_push

4. Setup + trusted_proxies

sudo docker exec -u abc nextcloud php /app/www/public/occ config:system:set trusted_proxies 3 --value=127.0.0.1
sudo 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. Ergebnis 2026-06-28: alle Checks grün, configuration saved.

5. Logs / Metriken prüfen

docker logs nextcloud-notify-push 2>&1 | tail -20
docker exec -u abc nextcloud php /app/www/public/occ notify_push:metrics

---

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 (2026-06-28)
• Sidecar lauscht auf Port 7867 (ss -tlnp im nextcloud-Netzns)
• notify_push:metrics erreichbar (Verbindungen steigen sobald Clients online)
• Weniger index.php/204 / status.php in Access-Log vs. vorher (24h Beobachtung)
• 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 (Referenz — ausgeführt 2026-06-28)

# Sidecar in compose.yml (siehe oben), dann:
cd /opt/stacks/nextcloud
sudo docker compose up -d notify_push

# App manuell + Setup
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 config:system:set trusted_proxies 3 --value=127.0.0.1
sudo docker exec -u abc nextcloud php /app/www/public/occ notify_push:setup https://cloud.jeanavril.com/push
sudo docker exec -u abc nextcloud php /app/www/public/occ notify_push:metrics

Snapshot vor Umsetzung: pre-notify-push-20260628 auf VM 101.

---

Alternative: Docker Mod (nicht nutzbar ohne Container-Internet)

Der Linuxserver Mod wäre wartungsärmer, scheiterte aber am fehlenden ausgehenden Internet im Nextcloud-Container. Falls Container-Netzwerk repariert wird, Mod erneut testen:

environment:
  - DOCKER_MODS=linuxserver/mods:nextcloud-notify-push

Dann Sidecar entfernen und docker compose up -d --force-recreate nextcloud.

---

Freigabe

☑	Freigegeben & umgesetzt — Sidecar (Mod wegen fehlendem Container-Internet verworfen)
☐	Anpassung
☐	Abgelehnt / später

Freigegeben von: Jean
Datum: 2026-06-28
Anmerkungen: Docker Mod getestet, Sidecar mit network_mode: service:nextcloud produktiv.

---

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