homelab-codex-ws/services/nextcloud

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.

TODO DECYZJA OSKARA: host (PIHA vs SOLARIA)

Otwarte w kb-02 i module 4. Compose jest przenośne (ścieżki po konwencji /opt/homelab/data, bind IP i proxy w .env) — decyzja wybiera node i dwie wartości w .env.

	PIHA	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	npm@PIHA proxuje po LAN do 192.168.31.70:8220 (npm proxuje na dowolny IP — bez przeszkód)
Wpływ na KB	żaden — KB czyta własną kopię z archiwum na PIHA w obu wariantach	jw.

Skłonność modułu 4: SOLARIA (dlatego service.yaml ma wstępnie owner_node: solaria, a env.example IP SOLARII). Koszt: przerwy w sync, gdy host śpi — do zaakceptowania, sync się dogoni.

Stack

Kontener	Obraz	Rola
nextcloud	nextcloud:stable-apache	app + WebDAV (port 80 → host 8220 na LAN_BIND_IP)
nextcloud-cron	nextcloud:stable-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)

TODO DECYZJA OSKARA: przy deployu przypiąć konkretną wersję major (np. nextcloud:31-apache) zamiast ruchomego stable — Nextcloud nie wspiera skoków o więcej niż jedną wersję major przy upgrade.

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:

# 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. Decyzja hosta ↑ podjęta; LAN_BIND_IP/TRUSTED_PROXIES w .env pod nią.
2. Port wolny na żywym hoście: ss -tlnp | grep 8220.
3. mkdir -p /opt/homelab/data/nextcloud/{html,db} na wybranym node.
4. .env z env.example.
5. DNS cloud.kapala.org → PIHA (DNS Only) + vhost w npm@PIHA (HTTPS → <LAN_BIND_IP>:8220; jeśli host=SOLARIA, target = 192.168.31.70).
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).