---
okf: "0.1"
type: incident
visibility: private
status: active
updated: 2026-08-03
links:
  - ../phases/backlog.md
---

## Fix: paperless-worker@SOLARIA — dwa bugi configu, naprawione i zweryfikowane na żywo (2026-07-12)

**Kontekst.** Moduł 3 (`services/paperless-worker/`, split-host OCR worker) był
zdeployowany i brał zadania z kolejki, ale miał dwa bugi w compose:

1. **`command: celery ...` nie odpalał celery.** Obraz paperless-ngx
   (`/sbin/docker-entrypoint.sh`) routuje każdy argument NIE zaczynający się
   od `/` do `manage.py` — więc `celery` lądował jako nieznana subkomenda
   Django, nie jako program. Fix: `command: /usr/sbin/gosu paperless
   /usr/local/bin/celery ...` (ścieżka absolutna wchodzi w gałąź `exec "$@"`
   entrypointu; `gosu paperless` z przodu bo ta gałąź nie dostaje automatycznego
   gosu, inaczej proces poszedłby jako root i zepsuł właściciela plików na NFS).
2. **Brak współdzielonego `SCRATCH_DIR`.** Paperless@PIHA staguje wgrywany
   plik w `/tmp/paperless` (domyślny `SCRATCH_DIR`) i niesie tę ścieżkę w
   payloadzie zadania celery jako ścieżkę absolutną. Worker@SOLARIA miał
   własny, lokalny `/tmp/paperless` — gdy odbierał zadanie zamiast workera
   PIHA, padał `Cannot consume ...: File not found`. Fix: NFS volume
   `paperless_scratch` (ten sam wzorzec co `data/media/consume`) na
   `/opt/homelab/data/paperless/scratch` (już istniał na PIHA, `chown 1000:1000`),
   mount na `/tmp/paperless` po obu stronach.

Oba fixy + uzasadnienie: `services/paperless/docker-compose.yml`,
`services/paperless-worker/docker-compose.yml`, `kb/services/paperless-worker.md`.
Zweryfikowane end-to-end na żywo (branch `task/paperless-worker-fix`, jeszcze
niezmergowany do master w momencie pisania tego wpisu): 3 dokumenty testowe
wrzucone do `consume/` na PIHA, jeden odebrany i dokończony przez worker@SOLARIA
(log: `ocrmypdf`/`tesseract` → `ConsumeTaskPlugin completed with: Success`),
zero `File not found`. Dokumenty testowe usunięte po teście (`document.delete()`
+ ręczny cleanup plików) — produkcyjne 6 dokumentów nietknięte.

**Otwarte (świadomie odłożone, nie blokuje działania):**
- `hosts/solaria/services.yaml` i `inventory/topology.yaml` nie mają wpisu
  `paperless-worker` (SOLARIA ma tam tylko `node-agent`) — było zaplanowane w
  cutover checkliście README jako krok "przy deployu", ale nigdy nie zrobione.
  Bez tego wpisu supervisor/observer nie widzą tego serwisu w desired-state —
  drift (np. worker padnie i nie wstanie) nie zostanie automatycznie wykryty
  przez agent system, tylko przez brak przetwarzania kolejki.
- Test formalnego fallbacku (stop worker@SOLARIA → kolejka mieli na PIHA →
  start → drenaż) nie był wykonany w tej sesji — mechanizm nie zmienił się
  tym fixem (był już OK), ale warto zweryfikować przy okazji.