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

---
okf: "0.1"
type: service
visibility: private
status: active
updated: 2026-07-12
links:
  - ../runbooks/paperless-worker-deploy.md
---

# Paperless OCR worker (SOLARIA)

Ciężki OCR filaru KB #2 (moduł 3, `kb/phases/kb-m3-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:

```bash
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):

```yaml
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.