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

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

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

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

```bash
# 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

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

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

```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:**

- [x] `notify_push:setup` ohne Fehler (2026-06-28)
- [x] Sidecar lauscht auf Port 7867 (`ss -tlnp` im nextcloud-Netzns)
- [x] `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)

```bash
# 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:

```yaml
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](nextcloud-tuning-freigabe.md) |
| Gesamt-Roadmap | [nextcloud-optimierung-und-updates.md](nextcloud-optimierung-und-updates.md) |