app-catalog-felhom.eu/templates/paperless-ngx/docker-compose.yml

# Paperless-ngx - Document Management System (DMS)
# Domain: ${SUBDOMAIN}.${DOMAIN}
# Database: PostgreSQL + Redis
# RAM: ~500MB (mem_limit: 1152M total — paperless 768M + postgres 256M + redis 128M) | Pi-compatible: Yes (arm64, 4GB+ RAM recommended)
#
# Environment variables:
#   DOMAIN                  - Your domain (e.g., demo-felhom.eu)
#   HDD_PATH                - Drive namespace root (managed media/export under appdata)
#   USERDATA_PATH           - Ügyfél-tartalom gyökér (<namespace>/userdata)
#   IMPORT_PATH             - KANONIKUS beolvasási gyökér a rendszerlemezen (R-75) — NEM az app lemezén
#   PAPERLESS_SECRET_KEY    - Random secret (auto-generated)
#   DB_PASSWORD             - PostgreSQL password (auto-generated)
#   PAPERLESS_ADMIN_USER    - Initial admin username (default: admin)
#   PAPERLESS_ADMIN_PASSWORD - Initial admin password
#
# Storage layout (felhom userdata convention):
#   Consume drop-zone → ${IMPORT_PATH}/paperless             (browsable — drop files here via FileBrowser)
#     ^ CANONICAL: one import root for the whole box, on the SYSTEM drive — NOT per data drive.
#       Each drop-zone app has exactly ONE ingest bind, so a per-drive import/ would put a folder
#       that looks like a drop-zone on every drive while only one of them does anything.
#   Document media    → ${HDD_PATH}/appdata/paperless/media  (app-managed originals + archive)
#   Export folder     → ${HDD_PATH}/appdata/paperless/export (app-managed backups)
#   App data/index    → paperless_data                       (named volume, NVMe)
# Run-identity: USERMAP_UID/GID 1000 → paperless consumes + DELETES from the import drop-zone
# (group 1000, setgid 2775) without permission errors.
#   PostgreSQL data  → paperless_postgres_data                   (named volume, NVMe)
#   Redis data       → paperless_redis_data                      (named volume, NVMe)
#
# First-time setup:
#   If PAPERLESS_ADMIN_USER/PASSWORD env vars are set, admin is auto-created.
#   Otherwise: docker exec -it paperless-webserver createsuperuser

services:
  paperless-webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15
    container_name: paperless-webserver
    restart: unless-stopped
    depends_on:
      paperless-postgres:
        condition: service_healthy
      paperless-redis:
        condition: service_healthy
    environment:
      - PAPERLESS_REDIS=redis://paperless-redis:6379
      - PAPERLESS_DBHOST=paperless-postgres
      - PAPERLESS_DBUSER=paperless
      - PAPERLESS_DBPASS=${DB_PASSWORD}
      - PAPERLESS_DBNAME=paperless
      - PAPERLESS_SECRET_KEY=${PAPERLESS_SECRET_KEY}
      - PAPERLESS_URL=https://${SUBDOMAIN}.${DOMAIN}
      - PAPERLESS_TIME_ZONE=Europe/Budapest
      # PAPERLESS_OCR_LANGUAGE selects the OCR engine language(s) — "+"-joined (e.g. hun+eng).
      # PAPERLESS_OCR_LANGUAGES is the INSTALL list and must be SPACE-separated (the image apt-installs
      # tesseract-ocr-<each>). Reusing the "+"-joined value here installed a bogus "tesseract-ocr-hun+eng"
      # → hun pack missing → Django check crash-loop. Fixed: a space-separated superset of every offered
      # option (eng bundled; hun/deu installed at boot — verified installable).
      - PAPERLESS_OCR_LANGUAGE=${PAPERLESS_OCR_LANGUAGE:-eng}
      - PAPERLESS_OCR_LANGUAGES=eng hun deu
      - PAPERLESS_ADMIN_USER=${PAPERLESS_ADMIN_USER:-}
      - PAPERLESS_ADMIN_PASSWORD=${PAPERLESS_ADMIN_PASSWORD:-}
      - PAPERLESS_CONSUMER_POLLING=30
      # R-514: ONE worker, one thread. Two workers were OOM-killed inside 768M by a 20-document batch
      # (BIGNIGHT 2026-09-14: 11 failed, 8 stuck, 0 consumed). Measured 2026-09-15 with 1x1: 20/20
      # consumed, memory.peak 783 294 464 B; the cap below is peak x 1.5 rounded up to 256M.
      - PAPERLESS_TASK_WORKERS=1
      - PAPERLESS_THREADS_PER_WORKER=1
      - USERMAP_UID=1000
      - USERMAP_GID=1000
      - TZ=Europe/Budapest
    volumes:
      - paperless_data:/usr/src/paperless/data
      - ${HDD_PATH}/appdata/paperless/media:/usr/src/paperless/media
      - ${IMPORT_PATH}/paperless:/usr/src/paperless/consume
      - ${HDD_PATH}/appdata/paperless/export:/usr/src/paperless/export
    networks:
      - traefik-public
      - paperless-internal
    deploy:
      resources:
        limits:
          memory: 1280M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://127.0.0.1:8000"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paperless.rule=Host(`${SUBDOMAIN}.${DOMAIN}`)"
      - "traefik.http.routers.paperless.entrypoints=websecure"
      - "traefik.http.routers.paperless.tls=true"
      - "traefik.http.routers.paperless.tls.certresolver=letsencrypt"
      - "traefik.http.services.paperless.loadbalancer.server.port=8000"

  paperless-postgres:
    image: postgres:18-alpine
    container_name: paperless-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=paperless
      - TZ=Europe/Budapest
    volumes:
      - paperless_postgres_data:/var/lib/postgresql
    networks:
      - paperless-internal
    deploy:
      resources:
        limits:
          memory: 256M
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless -d paperless"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  paperless-redis:
    image: redis:7-alpine
    container_name: paperless-redis
    restart: unless-stopped
    command: redis-server --appendonly yes
    environment:
      - TZ=Europe/Budapest
    volumes:
      - paperless_redis_data:/data
    networks:
      - paperless-internal
    deploy:
      resources:
        limits:
          memory: 128M
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  paperless_data:
  paperless_postgres_data:
  paperless_redis_data:

networks:
  traefik-public:
    external: true
  paperless-internal: