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".

Status (2026-07-12): ZDEPLOYOWANY I DZIAŁA. Worker bierze zadania z kolejki razem z workerem PIHA, kończy OCR bez błędów, dokumenty trafiają do Paperless niezależnie od tego, który worker odebrał zadanie. Zweryfikowane end-to-end: kilka dokumentów testowych wrzuconych do consume/ na PIHA, część odebrana przez worker@SOLARIA (log: Consuming ... → ocrmypdf/tesseract → ConsumeTaskPlugin completed with: Success → dokument widoczny w DB), zero File not found. Dwa bugi znalezione i naprawione po drodze — patrz sekcje „Gotcha: command i entrypoint obrazu" i „SCRATCH_DIR" niżej.

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.

Gotcha: command i entrypoint obrazu

Nadpisanie command: w compose na celery --app paperless worker ... (jak sugeruje GH discussion #3900 i punkt 1 wyżej) nie działa — pada Unknown command: 'celery'. Przyczyna w /sbin/docker-entrypoint.sh obrazu:

if [[ "$1" != "/"* ]]; then
    exec gosu paperless python3 manage.py "$@"   # argv[0] bez "/" -> manage.py
else
    exec "$@"                                     # argv[0] zaczyna się od "/" -> exec wprost
fi

Każdy argument NIE zaczynający się od / jest traktowany jako nazwa komendy Django i lądowany w manage.py <arg> — stąd celery jest interpretowane jako nieznana subkomenda manage.py, a nie program do uruchomienia. Fix: ścieżka absolutna, żeby wejść w gałąź exec "$@", plus jawne gosu paperless z przodu (bo ten branch NIE dostaje automatycznego gosu jak branch manage.py) — inaczej proces poszedłby jako root, co psuje właściciela plików na NFS (musi być uid 1000, patrz "UID mapping" niżej):

command: /usr/sbin/gosu paperless /usr/local/bin/celery --app paperless worker --loglevel INFO --concurrency ${WORKER_CONCURRENCY:-4}

Ścieżki zweryfikowane w obrazie ghcr.io/paperless-ngx/paperless-ngx:2.14: gosu = /usr/sbin/gosu, celery = /usr/local/bin/celery, user paperless = uid/gid 1000.

SCRATCH_DIR — musi być współdzielony tak samo jak data/media/consume

Paperless zapisuje wgrywany plik do katalogu roboczego przed konsumpcją — SCRATCH_DIR, domyślnie /tmp/paperless (paperless-ngx: tempfile.gettempdir() / "paperless" w src/paperless/settings.py, gdy PAPERLESS_SCRATCH_DIR nie jest ustawione — nie trzeba go więc ustawiać jawnie, domyślna wartość już pasuje do mount pointu poniżej). Payload zadania celery niesie ścieżkę do tego pliku jako ścieżkę absolutną. Ponieważ worker@PIHA i worker@SOLARIA dzielą jedną kolejkę, ten, który akurat odbierze zadanie, musi widzieć dokładnie ten sam plik pod dokładnie tą samą ścieżką — identyczna zasada jak dla data/media/consume (patrz komentarz w services/paperless/docker-compose.yml). To zostało pominięte przy pierwszym wdrożeniu modułu 3: dokumenty konsumowane na PIHA, ale odebrane do OCR przez SOLARIĘ, padały z Cannot consume ...: File not found, bo SOLARIA miała własny, lokalny, pusty /tmp/paperless. Fix: NFS-owy wolumen paperless_scratch (ten sam wzorzec co paperless_data/media/consume) na katalog /opt/homelab/data/paperless/scratch (już istnieje na PIHA, chown 1000:1000), montowany na /tmp/paperless po obu stronach.

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 (2026-07-12): PDF-y wrzucone do consume na PIHA, część odebrana i dokończona przez worker@SOLARIA (dowód w logach, zero File not found).
7. ⬜ Test fallbacku: stop workera → zadanie czeka/mieli PIHA → start → drenaż (jeszcze niewykonany formalnie, ale mechanizm nie zmienił się tym fixem — fallback na PIHA działał już wcześniej, patrz sekcja "Fallback" wyżej).
8. ⬜ OTWARTE: wpis paperless-worker w hosts/solaria/services.yaml + inventory/topology.yaml (obecnie SOLARIA ma tam tylko node-agent) — bez tego supervisor/observer nie widzą tego serwisu w desired-state, więc drift między hosts/solaria/services.yaml a rzeczywistością nie jest wykrywany. Patrz docs/backlog.md.