Skip to content
Klutch.sh Docs

Deploying a Papermerge App

Introduction

Papermerge is an open-source document management system focused on scanning, OCR, and organizing PDFs. Deploying Papermerge with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for documents and metadata—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 Papermerge Dockerfile (GitHub is the only supported git source)
  • PostgreSQL database (deploy as a Klutch.sh TCP app on port 8000 and connect on 5432) or SQLite for small tests
  • Optional Redis for caching/tasks (deploy as TCP on port 8000, connect on 6379)
  • Storage sizing for documents, media, and logs

For onboarding, see the Quick Start.

Architecture and ports

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

Repository layout

papermerge/
├── 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 papermerge-local .
docker run -p 8000:8000 \
  -e DJANGO_SETTINGS_MODULE=config.settings.production \
  papermerge-local

Dockerfile for Papermerge (production-ready)

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

FROM papermerge/papermerge:latest


ENV PORT=8000


EXPOSE 8000
CMD ["gunicorn", "-b", "0.0.0.0:8000", "-w", "2", "config.wsgi:application"]

Notes:

  • Pin the image tag (e.g., papermerge/papermerge:2.1.x) for stability; update intentionally.
  • Adjust worker count based on CPU/memory. Use the upstream entrypoint if preferred.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=8000
  • DJANGO_SETTINGS_MODULE=config.settings.production
  • SECRET_KEY=<secure-random>
  • Database (choose one):
    • PostgreSQL: DB_ENGINE=django.db.backends.postgresql, DB_HOST=<db-host>, DB_PORT=5432, DB_NAME=<db>, DB_USER=<user>, DB_PASSWORD=<password>
    • SQLite (not recommended for production): DB_ENGINE=django.db.backends.sqlite3, DB_NAME=/usr/src/papermerge/data/db.sqlite3
  • Redis (optional): REDIS_URL=redis://:<password>@<redis-host>:6379/0
  • OCR language and worker options as needed: PAPERMERGE_LANGUAGES=en, etc.

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=gunicorn -b 0.0.0.0:8000 -w 2 config.wsgi:application

Attach persistent volumes

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

  • /usr/src/papermerge/data — database (SQLite), cache, and internal data.
  • /usr/src/papermerge/media — uploaded documents and previews.
  • /usr/src/papermerge/logs — logs (optional).

Ensure these paths are writable inside the container.

Deploy Papermerge 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 SECRET_KEY.
  5. Attach persistent volumes for /usr/src/papermerge/data, /usr/src/papermerge/media, and /usr/src/papermerge/logs (if used) sized for your documents and logs.
  6. Deploy. Your Papermerge 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/" \
  -H "Authorization: Token <token>" \
  -F "document=@/path/to/file.pdf"

Health checks and production tips

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

Papermerge 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.