DEV Community

Cover image for Deploying Paperless-ngx Open-Source Document Management System on Ubuntu 24.04
Vultr profile image Sanskriti Harmukh
Sanskriti Harmukh for Vultr

Posted on with Aashish Chaurasiya • Originally published at docs.vultr.com

Deploying Paperless-ngx Open-Source Document Management System on Ubuntu 24.04

#selfhosted #docker #devops #ocr

Paperless-ngx is an open-source document management system that converts scans and PDFs into a fully searchable archive using Tesseract OCR, with tags, custom fields, and automated processing rules. This guide deploys Paperless-ngx using Docker Compose with PostgreSQL, Redis, and Traefik handling automatic HTTPS, then uploads a document and verifies OCR extraction. By the end, you'll have Paperless-ngx serving an OCR-indexed document archive securely at your domain.

Set Up the Directory Structure

1. Create the project directories:

$ mkdir -p ~/paperless-ngx/{data,media,export,consume,pgdata}
$ cd ~/paperless-ngx
Enter fullscreen mode Exit fullscreen mode

2. Create the environment file:

$ nano .env
Enter fullscreen mode Exit fullscreen mode 
DOMAIN=paperless.example.com
LETSENCRYPT_EMAIL=admin@example.com

PAPERLESS_SECRET_KEY=CHANGE_TO_RANDOM_STRING
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=UTC
PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_DBPASS=STRONG_PASSWORD_HERE

POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=STRONG_PASSWORD_HERE
Enter fullscreen mode Exit fullscreen mode

Use the same value for PAPERLESS_DBPASS and POSTGRES_PASSWORD. PAPERLESS_SECRET_KEY should be a 32+ character random string.

Deploy with Docker Compose

1. Create the Compose manifest:

$ nano docker-compose.yaml
Enter fullscreen mode Exit fullscreen mode 
services:
  traefik:
    image: traefik:v3.6
    container_name: traefik
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
    restart: unless-stopped

  db:
    image: postgres:16
    container_name: paperless-db
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - "./pgdata:/var/lib/postgresql/data"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}", "-d", "${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped

  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.6
    container_name: paperless
    depends_on:
      db:
        condition: service_healthy
    environment:
      PAPERLESS_REDIS: redis://redis:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_URL: ${PAPERLESS_URL}
      PAPERLESS_TIME_ZONE: ${PAPERLESS_TIME_ZONE}
      PAPERLESS_OCR_LANGUAGE: ${PAPERLESS_OCR_LANGUAGE}
      PAPERLESS_DBPASS: ${PAPERLESS_DBPASS}
    volumes:
      - "./data:/usr/src/paperless/data"
      - "./media:/usr/src/paperless/media"
      - "./export:/usr/src/paperless/export"
      - "./consume:/usr/src/paperless/consume"
    expose:
      - "8000"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.paperless.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.paperless.entrypoints=websecure"
      - "traefik.http.routers.paperless.tls.certresolver=letsencrypt"
      - "traefik.http.services.paperless.loadbalancer.server.port=8000"
    restart: unless-stopped
Enter fullscreen mode Exit fullscreen mode

2. Start the services:

$ docker compose up -d
$ docker compose ps
$ docker compose logs
Enter fullscreen mode Exit fullscreen mode

3. Create a superuser inside the Paperless container:

$ docker compose exec -it paperless python3 manage.py createsuperuser
Enter fullscreen mode Exit fullscreen mode

Follow the prompts for username, email, and password.

Upload a Document and Verify OCR

  1. Open https://paperless.example.com and sign in with the superuser.
  2. Click Upload documents at the top right and pick a PDF or image.
  3. Wait 5–30 seconds for Paperless to OCR the document.
  4. Click the thumbnail, then the Content tab — the extracted text appears alongside the document preview.

Next Steps

Paperless-ngx is running with PostgreSQL persistence and Tesseract OCR. From here you can:

  • Set up the Consume folder for automatic ingestion of scans dropped via SFTP or a scanner watch folder
  • Add tags, correspondents, document types, and storage paths for auto-classification
  • Enable additional OCR languages by adding ISO codes to PAPERLESS_OCR_LANGUAGE (e.g. eng+deu+fra)

For the full guide with additional tips, visit the original article on Vultr Docs.

Top comments (0)