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:

```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) |