jean/docu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doku: Freigabe-Dokument für notify_push (Linuxserver Docker Mod).

Browse Source 
Empfohlener Weg ohne NPM-Änderung; Sidecar als Alternative dokumentiert.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
root
2026-06-28 09:57:38 +02:00
parent 78583e5fda
commit 3b12324d4e
3 changed files with 346 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
migration/nextcloud-notify-push-freigabe.md
+341
View File
@@ -0,0 +1,341 @@
# 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:
```yaml
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`)
```bash
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
```bash
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
```bash
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
```bash
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):
```nginx
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):
```bash
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):
```bash
# 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
```bash
# 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)
```bash
# 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](nextcloud-tuning-freigabe.md) |
| Gesamt-Roadmap | [nextcloud-optimierung-und-updates.md](nextcloud-optimierung-und-updates.md) |