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.

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:

# 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).