Skip to content
Klutch.sh Docs

Deploying a Paperless-ngx App

Introduction

Paperless-ngx is an open-source document management system for ingesting, OCRing, and organizing PDFs and images. Deploying Paperless-ngx with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for documents and data—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Paperless-ngx Dockerfile (GitHub is the only supported git source)
  • PostgreSQL or SQLite (PostgreSQL recommended) as the database; deploy Postgres as a Klutch.sh TCP app on port 8000 and connect on 5432
  • Redis (optional for task queue/caching) as a Klutch.sh TCP app on port 8000 and connect on 6379
  • Storage sizing for documents, media, and logs

For onboarding, see the Quick Start.

Architecture and ports

  • Paperless-ngx serves HTTP on internal port 8000; choose HTTP traffic.
  • Persistent storage is required for documents, media, and data.

Repository layout

paperless-ngx/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t paperless-local .
docker run -p 8000:8000 \
  -e PAPERLESS_URL=https://localhost:8000 \
  paperless-local

Dockerfile for Paperless-ngx (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM ghcr.io/paperless-ngx/paperless-ngx:latest


ENV PAPERLESS_PORT=8000


EXPOSE 8000
CMD ["gunicorn", "-b", "0.0.0.0:8000", "-w", "2", "paperless.asgi:application", "-k", "uvicorn.workers.UvicornWorker"]

Notes:

  • Pin the image tag (e.g., ghcr.io/paperless-ngx/paperless-ngx:2.9.x) for stability; update intentionally.
  • Command uses the upstream entrypoint style; adjust workers based on memory/CPU.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PAPERLESS_URL=https://example-app.klutch.sh
  • PAPERLESS_PORT=8000
  • PAPERLESS_SECRET_KEY=<secure-random>
  • Database (choose one):
    • PostgreSQL: PAPERLESS_DBENGINE=postgresql, PAPERLESS_DBHOST=<db-host>, PAPERLESS_DBPORT=5432, PAPERLESS_DBNAME=<db>, PAPERLESS_DBUSER=<user>, PAPERLESS_DBPASS=<password>
    • SQLite (not recommended for production): PAPERLESS_DBENGINE=sqlite
  • Redis (optional): PAPERLESS_REDIS=redis://:<password>@<redis-host>:6379/0
  • OCR language packs and other options as needed: PAPERLESS_OCR_LANGUAGE=eng

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=gunicorn -b 0.0.0.0:8000 -w 2 paperless.asgi:application -k uvicorn.workers.UvicornWorker

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /usr/src/paperless/data — database (if SQLite) and data.
  • /usr/src/paperless/media — uploaded documents and previews.
  • /usr/src/paperless/export — exports.
  • /usr/src/paperless/consume — watch/import directory.
  • /usr/src/paperless/logs — logs (optional).

Ensure these paths are writable inside the container.

Deploy Paperless-ngx on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8000.
  4. Add the environment variables above, including database/Redis settings and a strong PAPERLESS_SECRET_KEY.
  5. Attach persistent volumes for /usr/src/paperless/data, /usr/src/paperless/media, /usr/src/paperless/export, and /usr/src/paperless/consume (plus /usr/src/paperless/logs if desired), sized for your documents and logs.
  6. Deploy. Your Paperless-ngx instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API usage

List documents (replace token with your auth token):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/documents/" \
  -H "Authorization: Token <token>"

Upload a document:

Terminal window
curl -X POST "https://example-app.klutch.sh/api/documents/post_document/" \
  -H "Authorization: Token <token>" \
  -F "document=@/path/to/file.pdf"

Health checks and production tips

  • Add an HTTP probe to / or /api/health if enabled.
  • Enforce HTTPS at the edge; forward internally to port 8000.
  • Keep database/Redis credentials and PAPERLESS_SECRET_KEY in Klutch.sh secrets; rotate regularly.
  • Monitor storage usage on data/media/export/consume; resize before they fill.
  • Pin image versions and test upgrades in staging; back up DB and volumes before updates.

Paperless-ngx on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8000 configured, and Postgres/Redis connected, you can run a reliable document management workflow without extra YAML or workflow overhead.