service:
  name: paperless
  owner_node: piha
  role: document-management     # KB pillar #2 source of truth for scans/invoices (archiwum = REFERENCJA)
  exposure: private             # LAN/Tailscale only via npm@PIHA (paper.kapala.org); NO public ingress
  dependencies:
    - forgejo                   # OIDC identity provider (forgejo.kapala.org)
  # paperless-worker@SOLARIA is a consumer of this service (Redis broker,
  # Postgres, NFS-exported storage) — not a dependency; the stack is fully
  # functional (slow OCR fallback) with SOLARIA powered down.
  ports:
    - container: 8000
      host: 8210                # LAN_BIND_IP only, never 0.0.0.0
      protocol: tcp
    - container: 5432
      host: 5434                # postgres for paperless-worker@SOLARIA (LAN bind)
      protocol: tcp
    - container: 6379
      host: 6380                # redis broker for paperless-worker@SOLARIA (LAN bind)
      protocol: tcp
  healthcheck:
    type: http
    endpoint: http://192.168.31.5:8210/    # LAN bind — localhost does not answer
    interval: 30s
    timeout: 10s
    retries: 5
  restart_policy: unless-stopped
  persistence:
    # Paperless is the KB REFERENCE archive — this storage is the single source
    # of truth for documents and its backup is MANDATORY (kb-02 hybrid boundary
    # condition). data/media/consume are also the NFS export consumed by
    # paperless-worker@SOLARIA.
    paths:
      - /opt/homelab/data/paperless/data      # search index, classifier — rebuildable
      - /opt/homelab/data/paperless/media     # ORIGINALS + archived PDFs — irreplaceable
      - /opt/homelab/data/paperless/consume   # ingest drop dir
      - /opt/homelab/data/paperless/export    # document_exporter output (backup staging)
      - paperless_pgdata                      # named volume: postgres (metadata, tags, correspondents)
      - paperless_redisdata                   # named volume: redis AOF (queued OCR tasks)
  runtime:
    config_files:
      - .env                    # secrets (gitignored, from env.example)
    env_vars:
      - LAN_BIND_IP             # required — compose port-bind interpolation (192.168.31.5)
      - PAPERLESS_SECRET_KEY
      - PAPERLESS_DBPASS
      - POSTGRES_PASSWORD       # must equal PAPERLESS_DBPASS
      - PAPERLESS_REDIS_PASSWORD   # broker requirepass; must equal paperless-worker@SOLARIA
      - PAPERLESS_SOCIALACCOUNT_PROVIDERS   # OIDC provider JSON incl. Forgejo client secret