How to Install Paperless-ngx with Docker Compose on Ubuntu

📄 This article is a translation and adaptation of the original post published in Bulgarian at itpraktika.com.

---

Introduction

Managing documents in a digital environment can quickly become overwhelming — especially as the number of files (PDFs, DOC files, scanned images) grows. Paperless-ngx is a modern Document Management System (DMS) that offers automatic indexing, OCR (Optical Character Recognition), and a powerful search engine.

In this guide, we'll walk through step by step how to install and configure Paperless-ngx using Docker Compose on Ubuntu, so it runs reliably and stably.

---

Prerequisites

Before we begin, make sure you have:

• Ubuntu server (20.04 or newer)
• Docker installed
• Docker Compose installed
• Terminal access (SSH)

💡 If you don't have Docker installed yet, check the official Docker documentation or a guide for your specific distro.

---

Step 1: Prepare the Directory Structure

Create the necessary folders for storing data:

mkdir -p /data/paperless/{data,media,export,consume,db}

Here's what each folder is for:

• data – metadata
• media – the actual document files
• export – exported documents
• consume – incoming folder for automatic import
• db – database files

---

Step 2: Create the docker-compose.yml File

Create the file:

nano docker-compose.yml

Then paste in the following configuration:

version: "3.8"

services:
  broker:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped
    command: redis-server --save "" --appendonly no

  db:
    image: postgres:15
    container_name: paperless-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless_password_change_me
    volumes:
      - /data/paperless/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless"]
      interval: 10s
      timeout: 5s
      retries: 5

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      broker:
        condition: service_started
    ports:
      - "8000:8000"
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless_password_change_me

      # Uncomment if using a domain:
      # PAPERLESS_URL: https://paperless.yourdomain.com
      # PAPERLESS_CSRF_TRUSTED_ORIGINS: https://paperless.yourdomain.com

      PAPERLESS_SECRET_KEY: "change_me_to_something_long_and_random"
      USERMAP_UID: 1000
      USERMAP_GID: 1000

      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_TIME_ZONE: Europe/London
      PAPERLESS_OCR_LANGUAGES: eng

      PAPERLESS_CONSUMER_POLLING: 60
      PAPERLESS_FILENAME_FORMAT: "{created_year}/{correspondent}/{title}"

    volumes:
      - /data/paperless/data:/usr/src/paperless/data
      - /data/paperless/media:/usr/src/paperless/media
      - /data/paperless/export:/usr/src/paperless/export
      - /data/paperless/consume:/usr/src/paperless/consume

🔐 Important: Change paperless_password_change_me and PAPERLESS_SECRET_KEY to strong, unique values before deploying.

---

Step 3: Start the Containers

Run:

docker compose up -d

After a few seconds, the system will be accessible at:

http://YOUR_SERVER_IP:8000

---

Step 4: Create an Admin User

No default user is created automatically. You need to create one manually:

docker exec -it paperless python3 manage.py createsuperuser

You'll be prompted to enter:

• Username
• Email (optional)
• Password

After that, you can log into the web interface.

---

Step 5: Working with Documents

Uploading Files

You have several options:

• Drag & Drop in the browser
• The Upload button in the UI
• Automatic import via the consume folder:

cp *.pdf /data/paperless/consume/

All files placed in that folder will be processed automatically.

---

Step 6: ⚠️ Domain Configuration (IMPORTANT)

If you plan to use a domain (e.g., behind Cloudflare or nginx), you must add the following environment variables:

PAPERLESS_URL: https://your-domain.com
PAPERLESS_CSRF_TRUSTED_ORIGINS: https://your-domain.com

⚠️ Important notes:

• Do NOT add a trailing slash / at the end of the URL
• If you use www, add both versions:

PAPERLESS_CSRF_TRUSTED_ORIGINS: https://your-domain.com,https://www.your-domain.com

Why is this necessary?

Without these settings, you will get a 403 CSRF verification failed error. This is a built-in security mechanism that requires the domain to be explicitly trusted.

---

Common Issues

1. Can't log in

• Make sure you created a superuser (Step 4)
• Try clearing your browser cache/cookies

2. OCR not working

• Verify that all containers are running: docker compose ps
• Check language settings in your environment variables

3. Slow processing

• This is normal during the initial indexing phase
• OCR is CPU-intensive — be patient on lower-end hardware

---

Best Practices

• Use strong, unique passwords
• Set up regular backups:

  rsync -av /data/paperless /backup/

• Use the /consume folder to automate document ingestion
• Organize documents with tags and correspondents from the start

---

Conclusion

Once you've completed the setup, you'll quickly appreciate how much easier document management becomes. Paperless-ngx isn't just a file store — it's a tool that genuinely saves time when searching, sorting, and organizing information.

A few long-term recommendations:

• Set up automated backups from day one
• Use a domain with HTTPS if accessible over the internet
• Restrict access if the instance is publicly reachable

Don't be afraid to experiment. Paperless-ngx has a lot of automation and customization options you can tune to your workflow. With the right setup and a small initial investment of time, you'll have a fast, reliable, and user-friendly document management system.

---

📄 Original article in Bulgarian: Как да инсталираме Paperless-ngx с Docker Compose — itpraktika.com