homelab-codex-ws/services/paperless-worker/service.yaml

service:
  name: paperless-worker
  owner_node: solaria
  role: ocr-compute-worker      # heavy OCR for paperless@PIHA; "compute on-demand z fallback" pattern
  exposure: local-only          # no listening ports at all — outbound-only celery worker
  dependencies:
    - paperless                 # broker (redis 192.168.31.5:6380), DB (:5434) and NFS storage @ PIHA
  ports: []                     # none — connects out, serves nothing
  healthcheck:
    type: command
    # celery ping through the broker: proves both broker reachability and a
    # live worker process. Runs inside the container.
    endpoint: docker exec paperless-worker celery --app paperless inspect ping --timeout 10
    interval: 60s
    timeout: 15s
    retries: 3
  restart_policy: unless-stopped
  # SOLARIA is a session-availability node: this worker being down is a NORMAL
  # state, not an incident. Queued OCR tasks wait in Redis@PIHA (AOF) and the
  # built-in concurrency-1 worker on PIHA grinds slowly meanwhile.
  persistence:
    # Nothing to back up here — all document state lives on PIHA (owner:
    # services/paperless). The NFS volumes below are mounts of PIHA data,
    # backed up on the PIHA side.
    paths: []
  runtime:
    config_files:
      - .env                    # secrets shared with paperless@PIHA (gitignored, from env.example)
    env_vars:
      - PAPERLESS_SECRET_KEY    # MUST equal the value on PIHA
      - PAPERLESS_DBPASS        # MUST equal the value on PIHA
      - PAPERLESS_REDIS_PASSWORD   # MUST equal the value on PIHA (broker requirepass)
      - WORKER_CONCURRENCY      # optional, default 4 — parallel OCR tasks