# Nextcloud (drive / WebDAV)

Drugi adapter dokumentów filaru KB #2 (moduł 4, `docs/kb/modules/04-nextcloud.md`):
zamiennik Google Drive — dowolne pliki + sync telefon/desktop, źródło dla
ingestu KB (moduł 5) przez WebDAV.

**Nextcloud = archiwum KOPIA w hybrydzie kb-02** — ingest robi snapshot pliku
do archiwum KB; Nextcloud NIE jest źródłem prawdy (inaczej niż Paperless).
Backup „warto" (dane użytkownika), ale nie jest warunkiem brzegowym KB.

## Decyzja: host = PIHA

Moduł 4 skłaniał się ku SOLARIA (mocniejszy host, bez wpływu na KB — patrz
niżej), ale Oskar zdecydował inaczej: **Nextcloud jest używany aktywnie**
(telefon, sync, rodzina) — sesyjna dostępność SOLARII (sync dogania się
dopiero po wybudzeniu hosta) nie jest akceptowalna dla tego workloadu.
Nextcloud musi być **always-on**, więc ląduje na PIHA mimo ciaśniejszego
RAM/CPU.

| | PIHA (wybrane) | SOLARIA |
|---|---|---|
| Dostępność | 24/7 (sync zawsze działa) | sesyjna — sync dogania się po wybudzeniu |
| RAM/CPU | ciasno nawet po module 0 (Nextcloud+PHP ≈ 0.5–1 Gi+) | 62 Gi RAM, 24 rdzenie — bez znaczenia |
| Storage | NVMe 477 G (dzielone z resztą) | NVMe 2 T |
| Ingress | npm lokalnie (ten sam host) | npm@PIHA proxuje po LAN do 192.168.31.70:8220 |
| Wpływ na KB | żaden — KB czyta własną kopię z archiwum na PIHA w obu wariantach | jw. |

`service.yaml` ma `owner_node: piha`; `env.example` ma `LAN_BIND_IP` PIHA
(192.168.31.5) i `TRUSTED_PROXIES` pod docker bridge (npm i nextcloud na
tym samym hoście — patrz komentarz w `env.example`). Compose zostaje
przenośne (ścieżki po konwencji `/opt/homelab/data`), gdyby host kiedyś
się zmienił.

## Stack

| Kontener         | Obraz                   | Rola                                  |
|------------------|-------------------------|---------------------------------------|
| `nextcloud`      | `nextcloud:34-apache` | app + WebDAV (port 80 → host 8220 na LAN_BIND_IP) |
| `nextcloud-cron` | `nextcloud:34-apache` | joby w tle (`/cron.sh`, ten sam wolumen) |
| `nextcloud-db`   | `postgres:16-alpine`    | baza (bez portu na hoście)             |
| `nextcloud-redis`| `redis:7-alpine`        | cache + file locking (bez portu, bez persystencji) |

Wersja przypięta na `34-apache` (aktualny stable na 2026-07-09, wydany
2026-06-09 — zweryfikowane przez endoflife.date/nextcloud). Nextcloud
wydaje nowy major co ~4 miesiące i nie wspiera przeskakiwania wersji przy
upgrade — **TODO PRZY DEPLOYU**: potwierdzić bieżący stable tuż przed
`docker compose up` i podbić tag, jeśli wyszła nowsza wersja.

## OIDC przez Forgejo (krok po-deployowy, occ)

Mechanizm: oficjalna appka **`user_oidc`** (utrzymywana przez Nextcloud GmbH —
wybieramy ją zamiast community `sociallogin`). Konfiguruje się ją przez `occ`
po pierwszym starcie — NIE przez env, stąd kroki w checkliście:

```bash
# w kontenerze nextcloud, jako www-data:
docker exec -u www-data nextcloud php occ app:install user_oidc
docker exec -u www-data nextcloud php occ user_oidc:provider forgejo \
  --clientid="<CLIENT_ID>" \
  --clientsecret="<CLIENT_SECRET>" \
  --discoveryuri="https://forgejo.kapala.org/.well-known/openid-configuration" \
  --scope="openid profile email" \
  --unique-uid=0 \
  --mapping-display-name=name --mapping-email=email --mapping-uid=preferred_username
```

Rejestracja w Forgejo (Settings → Applications, wzorzec jak Vikunja):

- Redirect URI: `https://cloud.kapala.org/apps/user_oidc/code`
- Confidential client; scope `openid profile email`

`forgejo.kapala.org` jest przypięte w compose przez `extra_hosts` do
`192.168.31.5` (npm@PIHA) — OIDC discovery po LAN, lekcja z Vikunji.
`--unique-uid=0` + mapping `preferred_username` daje czytelne loginy
(np. `oskar`) zamiast hashowanych ID — istotne dla WebDAV-owych URL-i.

## WebDAV dla ingestu (moduł 5)

Endpoint: `https://cloud.kapala.org/remote.php/dav/files/<user>/`.
Konta OIDC nie mają hasła — dla ingestu wygenerować **app password**
(Settings → Security → Devices & sessions) i trzymać je w sekretach
adaptera ingest, nie w tym repo.

## Storage i backup

- `/opt/homelab/data/nextcloud/html` — aplikacja + config + **pliki
  użytkowników** (`html/data/`)
- `/opt/homelab/data/nextcloud/db` — Postgres

TODO DECYZJA OSKARA: backup user-data (mniej krytyczny niż Paperless, bo
KB trzyma kopie zaingestowanych plików): propozycja — rsync/borg
`html/data` + `pg_dump` w tej samej nocnej pętli co backup Paperlessa,
retencja krótsza (np. 7 dziennych + 4 tygodniowe).

## Cutover checklist (przy deployu — NIE teraz)

1. Host = PIHA (decyzja podjęta); `LAN_BIND_IP`/`TRUSTED_PROXIES` w `.env`
   już pod nią — `TRUSTED_PROXIES` doprecyzować przez `docker network
   inspect` na żywym hoście (patrz komentarz w `env.example`).
2. Port wolny na żywym hoście: `ss -tlnp | grep 8220`.
3. `mkdir -p /opt/homelab/data/nextcloud/{html,db}` na PIHA.
4. `.env` z `env.example`.
5. DNS: rekord A `cloud.kapala.org` w Cloudflare → `100.108.208.3`
   (Tailscale PIHA, DNS Only) — ten sam wzorzec co `ha.kapala.org` /
   `immich.kapala.org` (`docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md`);
   wildcard `*.kapala.org` już pokrywa tę subdomenę, nowy cert niepotrzebny.
   Plus vhost w npm@PIHA (HTTPS → `192.168.31.5:8220`, Advanced puste).
6. `docker compose up -d`; pierwszy start instaluje NC (2–3 min),
   potem `./healthcheck.sh`.
7. Kroki `occ` dla `user_oidc` (wyżej) + rejestracja appki w Forgejo +
   testowy login OIDC.
8. Test sync klientem (telefon) + test WebDAV (`curl -u user:app-password`).
9. Wpis w `hosts/<node>/services.yaml` + topology (dopiero przy deployu).