homelab-codex-ws/services/paperless-worker/README.md

Paperless OCR worker (SOLARIA)

Ciężki OCR filaru KB #2 (moduł 3, docs/kb/modules/03-paperless-ocr-worker.md). Ten sam obraz co services/paperless/, ale z nadpisanym poleceniem — działa wyłącznie jako celery worker podpięty do brokera/bazy paperless@PIHA, ze storage widzianym przez NFS z PIHA. Realizuje wzorzec kb-02 „serwis always-on + compute-worker on-demand z fallback".

Wynik badania: czy split-host worker jest wykonalny?

TAK — z zastrzeżeniami. Ustalenia (GH discussion #3900 + docs):

1. Nie jest to oficjalnie wspierane przez Paperless-ngx, ale maintainerzy potwierdzają wykonalność i podają dokładnie ten wzorzec: drugi host, ten sam obraz, command: celery --app paperless worker --loglevel INFO, dostęp sieciowy do Redis + Postgres + współdzielonych plików.
2. Worker potrzebuje pełnego kontekstu aplikacji: broker (Redis), baza (Postgres) i te same pliki pod tymi samymi ścieżkami kontenerowymi (/usr/src/paperless/{data,media,consume}) — payloady zadań i DB niosą ścieżki absolutne.
3. Podział pracy: consumer (inotify na consume/), beat (harmonogram) i webserver zostają na PIHA; na SOLARIA idzie wyłącznie egzekucja zadań celery (OCR/parsowanie/archiwizacja). Consumer na PIHA działa na lokalnym dysku, więc inotify działa normalnie (ograniczenie „inotify nie działa po NFS" nas nie dotyka — po NFS czyta tylko worker, nie consumer).
4. Fallback: obu-stronny worker na tej samej kolejce. Gdy SOLARIA śpi — zadania czekają w Redis (AOF na PIHA) i wbudowany worker PIHA (concurrency 1) mieli powoli. Gdy SOLARIA wstaje — worker z concurrency 4+ rozładowuje kolejkę. Gdy worker zniknie w połowie zadania, celery na transporcie redis odda nieodebrane zadanie po visibility timeout (domyślnie 1 h) — zadanie nie ginie, najwyżej się opóźnia.
5. GPU nie gra roli — stockowy OCR (ocrmypdf/tesseract) jest CPU-only. Zysk SOLARII to 24 rdzenie i 62 Gi RAM, nie CUDA.

Znane ryzyka (świadomie zaakceptowane / do obserwacji)

• Indeks Whoosh w data/ przy dwóch piszących hostach. Po konsumpcji dokumentu worker dopisuje go do indeksu wyszukiwania (plikowy Whoosh w data/index). Przy workerze na PIHA (lokalnie) i na SOLARIA (po NFS) równolegle istnieje ryzyko wyścigu na lockach plikowych (znane objawy w upstream: „This writer is closed", skorumpowany TOC indeksu). Mitygacja: indeks to dane pochodne — docker exec paperless document_index reindex odtwarza go w całości; oryginały i metadane nie są zagrożone. Jeśli korupcje będą się powtarzać, opcje: przenieść cały batch-OCR w okna, gdy działa tylko jeden worker, albo zrezygnować z fallbacku PIHA (kolejka po prostu czeka na SOLARIĘ).
• Postgres max_connections: każdy proces workera trzyma połączenie. Przy defaultowym 100 i concurrency 4+1 zapasu jest dużo; podbijając WORKER_CONCURRENCY pilnować sumy połączeń (formuła w docs upstream).
• Wersje obrazów muszą być identyczne (PIHA i SOLARIA) — wspólny schemat DB i sygnatury zadań. Podbijać oba compose naraz.

NFS: export na PIHA, mount na SOLARIA

Transfer idzie po LAN (PIHA 192.168.31.5 ↔ SOLARIA 192.168.31.70, 1 Gb/s, ten sam switch) — NIE po Tailscale. Przepustowość nie jest wąskim gardłem OCR.

Host-side na PIHA (NIE w compose — krok przy deployu modułu 3)

# /etc/exports na PIHA — export TYLKO dla SOLARII:
/opt/homelab/data/paperless 192.168.31.70(rw,sync,no_subtree_check,no_root_squash)

sudo apt install nfs-kernel-server   # jesli brak
sudo exportfs -ra

no_root_squash jest potrzebne, bo entrypoint obrazu (root) robi chown na katalogach przy starcie kontenera na SOLARII; export jest ograniczony do jednego IP w zaufanym LAN.

Strona SOLARII

Mounty definiuje compose jako named volumes z driverem NFS — zero wpisów w /etc/fstab; jedyny host-side wymóg to pakiet klienta:

sudo apt install nfs-common

UID mapping (krytyczne)

Pliki na exporcie mają numerycznego właściciela — NFS nie tłumaczy nazw. Dlatego USERMAP_UID/GID=1000 jest ustawione w obu compose (PIHA i SOLARIA); zmiana po jednej stronie = worker traci dostęp do plików. Weryfikacja po deployu: ./healthcheck.sh robi test zapisu na mount.

Cutover checklist (przy deployu modułu 3 — po działającym module 2)

1. services/paperless/ działa na PIHA (healthcheck zielony).
2. Export NFS na PIHA (wyżej) + showmount -e 192.168.31.5 z SOLARII.
3. nfs-common na SOLARII.
4. .env z env.example — sekrety SKOPIOWANE z PIHA, nie nowe.
5. docker compose up -d + ./healthcheck.sh.
6. Test: wrzucić PDF do consume na PIHA → obciążenie CPU na SOLARII, nie PIHA.
7. Test fallbacku: stop workera → zadanie czeka/mieli PIHA → start → drenaż.
8. Wpis w hosts/solaria/services.yaml + topology (dopiero przy deployu).