Hosting paperless-ngx

paperless-ngx is a document organization and management system.

Docker-based Setup

See also

Paperless-ngx has excellent documentation to reference:

• Docker compose setup: https://docs.paperless-ngx.com/setup/#docker
• Environ config reference: https://docs.paperless-ngx.com/configuration/
• Paperless-side SSO docs: https://docs.paperless-ngx.com/advanced_usage/?h=sso#sso-and-third-party-authentication-with-paperless-ngx
• Authentik-side SSO docs: https://integrations.goauthentik.io/documentation/paperless-ngx/

The following compose file hosts three things:

• paperless-broker: redis, for paperless microservices communicating with each other
• paperless-db: a Postgres database for backend storage
• paperless-web: the web frontend and main program

These examples are also configured for a few other personal preferences:

• Allow import jobs to continue if the OCR task fails
• SSO with Authentik

services:
  paperless-broker:
    container_name: paperless_broker
    image: docker.io/library/redis:8
    restart: unless-stopped
    volumes:
      - /medium/storage/for/broker:/data
 
  paperless-db:
    container_name: paperless_db
    image: docker.io/library/postgres:18
    restart: unless-stopped
    env_file:
      - paperless.env
    volumes:
      - /big/storage/for/database:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
 
  paperless-web:
    container_name: paperless_web
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    env_file:
      - paperless.env
    depends_on:
      - paperless-broker
      - paperless-db
    #ports:  # if you're not using a reverse proxy
      #- 8000:8000
    volumes:
      - /big/storage/for/data:/usr/src/paperless/data
      - /big/storage/for/media:/usr/src/paperless/media
      - /medium/storage/for/exports:/usr/src/paperless/export
      - /medium/storage/for/imports:/usr/src/paperless/consume
    environment:
      PAPERLESS_OCR_USER_ARGS: '{"continue_on_soft_render_error": true}'
      PAPERLESS_URL: https://paperless.example.com
      PAPERLESS_REDIS: redis://paperless-broker:6379
      PAPERLESS_DBHOST: paperless-db
      USERMAP_UID: 1000
      USERMAP_GID: 1000

The associated paperless.env file contains:

POSTGRES_USER=supersecretuser
POSTGRES_PASSWORD=supersecretpassword
PAPERLESS_SOCIALACCOUNT_PROVIDERS={"openid_connect": {"OAUTH_PKCE_ENABLED": true, "APPS": [{"provider_id": "authentik", "name": "authentik", "client_id": "12345", "secret": "12345", "settings": {"server_url": "https://auth.example.com/application/o/paperless-ngx/.well-known/openid-configuration", "fetch_userinfo": true}}], "SCOPE": ["openid", "profile", "email"]}}
PAPERLESS_LOGOUT_REDIRECT_URL=https://auth.example.com/application/o/paperless-ngx/end-session/
PAPERLESS_SOCIAL_AUTO_SIGNUP=true
PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS=true
PAPERLESS_DISABLE_REGULAR_LOGIN=true
PAPERLESS_REDIRECT_LOGIN_TO_SSO=true
PAPERLESS_APPS=allauth.socialaccount.providers.openid_connect
PAPERLESS_SECRET_KEY=supersecret