homelab-codex-ws/kb/decisions/kb-dokumenty-otwarte.md

okf	type	visibility	status	updated	links
0.1	decision	private	planned	2026-07-09

Decyzje do podjęcia — filar dokumentów (moduły 2/3/4)

Zbiorcza lista decyzji z przygotowania configów (2026-07-06, branch task/paperless-nextcloud-config; decyzje podjęte 2026-07-09, branch task/paperless-decyzje). Configi są zaktualizowane wg decyzji poniżej — NIC nie zostało zdeployowane, ten etap to tylko edycja plików w repo.

Otwarte — do zrobienia PRZY DEPLOYU (nie są to już decyzje, tylko kroki wykonawcze)

3. Porty (potwierdzić na żywym PIHA przed deployem)

Dobrane wg inwentaryzacji 2026-06-30 (snapshot! zweryfikować ss -tlnp):

Port	Serwis	Uwagi
8210	paperless web	za npm@PIHA
5434	paperless postgres	5433 zajęte przez kb-postgres
6380	paperless redis (broker dla workera)	6379 zajęte przez agent-system-redis
8220	nextcloud web	teraz na PIHA (decyzja #1) — potwierdzić że nadal wolny

Wszystkie bindowane na LAN IP (nie 0.0.0.0); ruch worker↔broker/DB/NFS po LAN 192.168.31.x, nie Tailscale.

7. Wyłączenie lokalnego loginu w Paperless po weryfikacji OIDC

Bootstrap idzie przez lokalnego admina (PAPERLESS_ADMIN_USER). Po potwierdzeniu działania Forgejo-OIDC: ustawić PAPERLESS_DISABLE_REGULAR_LOGIN=true + PAPERLESS_REDIRECT_LOGIN_TO_SSO=true (decyzja podjęta — wykonać dopiero po potwierdzonym logowaniu OIDC; Vikunja ma dziś oba tryby równolegle, ten sam wzorzec przejściowy).

9. Sizing workera OCR pod batch 70k załączników

WORKER_CONCURRENCY=4 × PAPERLESS_THREADS_PER_WORKER=4 = ~16 wątków na 24 rdzeniach SOLARII. Przed batchem 70k (moduł 5): zmierzyć na próbce i zdecydować, czy podbić concurrency, czy zostawić zapas na ollama/AI.

---

Rozstrzygnięte

• 1. Host Nextclouda: PIHA. Oskar używa Nextclouda aktywnie (telefon, sync, rodzina) → musi być always-on; sesyjna dostępność SOLARII (sync dogania się dopiero po wybudzeniu) nie jest akceptowalna dla tego workloadu — mimo że moduł 4/kb-02 skłaniały się ku SOLARII (KB i tak czyta własną kopię z archiwum na PIHA, więc host Nextclouda nie warunkuje zapytań KB). service.yaml: owner_node: piha. .env: LAN_BIND_IP = 192.168.31.5, TRUSTED_PROXIES = docker bridge subnet (npm i nextcloud na tym samym hoście teraz). Uzasadnienie pełne: services/nextcloud/README.md.

• 2. Backup Paperlessa: SOLARIA (LAN), na start. Nocny document_exporter (oryginały + archiwa + manifest, odtwarzalny bez dumpa SQL) → /opt/homelab/data/paperless/export, kopia poza hosta przez rsync/borg → SOLARIA (2 TB, ta sama LAN). Retencja: 7 dziennych + 4 tygodniowe + 6 miesięcznych. Offsite (np. restic → chmura) zostaje jako future-note, poza zakresem tego etapu. Cron/skrypt deployowy powstaje przy deployu modułu 2, nie teraz. Szczegóły: kb/services/paperless.md.

• 4. Redis brokera: requirepass. Broker (6380) dostaje hasło — PAPERLESS_REDIS_PASSWORD w .env po obu stronach (paperless@PIHA, paperless-worker@SOLARIA), placeholder CHANGEME w env.example, realne hasło tylko w .env (gitignored). Healthchecki obu stron zaktualizowane o auth.

• 5. Fallback-worker na PIHA a indeks Whoosh po NFS: zaakceptować i obserwować. Ryzyko wyścigu na plikowym indeksie Whoosh (PIHA lokalnie

  • SOLARIA po NFS) świadomie zaakceptowane — indeks jest odtwarzalny (document_index reindex), oryginałom nic nie grozi. Bez zmian w configu; fallback-worker na PIHA zostaje. Szczegóły: kb/services/paperless-worker.md.

• 6. Domeny: kapala.org (mesh, prywatne). paper.kapala.org (Paperless), cloud.kapala.org (Nextcloud) — potwierdzone, *.okit.pl odrzucone. DNS i vhosty NIE utworzone w tym etapie — tylko udokumentowane w READMY serwisów (wzorzec: rekord A w Cloudflare → 100.108.208.3, Tailscale PIHA, DNS Only, ten sam co ha.kapala.org/immich.kapala.org — docs/sessions/2026-06-30-kapala-cloudflare-wildcard-mesh.md; wildcard *.kapala.org już pokrywa obie subdomeny, nowe certy niepotrzebne). OAuth redirect URIs w Forgejo apps zapisane w READMY obu serwisów.

• 8. Pin wersji Nextclouda: 34-apache. Zweryfikowany aktualny stable na 2026-07-09 (wydany 2026-06-09, endoflife.date/nextcloud). Zamiast ruchomego stable-apache. 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, podbić tag jeśli wyszła nowsza wersja.

• Split-host OCR-worker przez NFS: WYKONALNY — wzorzec potwierdzony przez maintainerów paperless-ngx (nieoficjalnie wspierany): ten sam obraz, command: celery --app paperless worker, wspólny Redis+Postgres+storage, identyczne ścieżki kontenerowe i numeryczny UID po obu stronach. Pełny wynik badania + ryzyka: kb/services/paperless-worker.md.

• Storage dokumentów na PIHA; NFS export → SOLARIA po LAN (192.168.31.5 → 192.168.31.70), nie Tailscale.

• AOF w Redis brokera (kolejka przeżywa restart — zero utraty zadań).

• OIDC: Paperless przez django-allauth openid_connect (env), Nextcloud przez appkę user_oidc (kroki occ w README).

• Limity RAM na PIHA: hosts/piha/runtime/paperless/docker-compose.override.yml (stack ≤ ~1.9 Gi worst-case).