Self-Host Paperless-ngx: The Ultimate Document Management Guide

Transform Your Paper Clutter into a Searchable Archive

Physical filing cabinets are relics that occupy space and make retrieving information a chore. Paperless-ngx is a community-driven, open-source document management system (DMS) that transforms your physical documents into a searchable, organized digital archive. By using Optical Character Recognition (OCR), it reads your scanned PDFs and images, making every word searchable.

In this guide, we will walk through setting up Paperless-ngx using Docker Compose, configuring the OCR engine, and establishing a workflow for your digital documents.

Why Choose Paperless-ngx?

Unlike simple cloud storage like Google Drive or Dropbox, Paperless-ngx is designed specifically for document workflows.

• Full-Text Search: Every document is indexed. You can search for a specific receipt by the name of the store or a date mentioned in the fine print.
• Automated Tagging: It uses machine learning to learn how you categorize documents. Over time, it will automatically assign tags, correspondents, and document types.
• OCR Support: Powered by Tesseract, it handles multi-language OCR out of the box.
• Self-Hosted Privacy: Your sensitive financial and personal documents never leave your local hardware.

Prerequisites

Before we begin the installation, ensure your system meets the following requirements:

1. A Linux server (Ubuntu 22.04 or 24.04 is recommended).
2. Docker and Docker Compose installed. If you haven’t set this up yet, follow our Ubuntu Docker installation guide.
3. At least 2GB of RAM (OCR processing can be resource-intensive).
4. Basic knowledge of the terminal.

Step 1: Prepare the Project Directory

First, create a dedicated directory for Paperless-ngx to keep your configuration and data organized.

mkdir ~/paperless-ngx && cd ~/paperless-ngx
mkdir config data consume media export

• consume: This is where you will drop new files to be processed.
• media: This stores the actual encrypted or processed files.
• data: This holds the application’s internal search index and state.

Step 2: Create the Docker Compose Configuration

Paperless-ngx requires a few moving parts: the main application web server, a Redis instance for task queuing, and a database (PostgreSQL is recommended).

Create a new file named docker-compose.yml:

nano docker-compose.yml

Paste the following configuration:

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: your_secure_password

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8010:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db

Step 3: Configure Environment Variables

Create the docker-compose.env file to handle specific application settings like OCR languages and timezones.

nano docker-compose.env

Add the following variables:

# The URL Paperless will be accessible at
PAPERLESS_URL=http://your-server-ip:8010

# Security settings
PAPERLESS_SECRET_KEY=use-a-long-random-string-here

# OCR settings
PAPERLESS_OCR_LANGUAGE=eng
PAPERLESS_TIME_ZONE=UTC

# Database settings (Must match the db service above)
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_secure_password
PAPERLESS_DBNAME=paperless

Note: If you plan on exposing this to the internet, make sure to follow our Nginx Proxy Manager security guide to set up HTTPS and a reverse proxy.

Step 4: Deploy and Create an Admin User

With the files in place, pull the images and start the containers:

docker compose up -d

Once the containers are running, you need to create a “superuser” to log into the web interface:

docker compose exec webserver python3 manage.py createsuperuser

Follow the prompts to set your username, email, and password.

Step 5: Accessing the Dashboard

Open your web browser and navigate to http://your-server-ip:8010. Log in with the credentials you just created.

You can now start uploading documents via the web UI or by dropping files into the ~/paperless-ngx/consume folder on your server. Paperless-ngx will automatically pick them up, perform OCR, and display them in your inbox.

Common Issues & Troubleshooting

• Permission Denied on Consumption Folder: If the container cannot read files dropped into the consume folder, ensure the folder has the correct permissions. You can try chmod -R 777 consume as a temporary test, though more restrictive ownership is better for production.
• High CPU Usage: During the initial import of large PDF libraries, CPU usage will spike as the OCR engine processes each page. This is normal.
• Database Connection Refused: Ensure the POSTGRES_PASSWORD in the db service matches PAPERLESS_DBPASS in the .env file.

Next Steps

Now that your digital archive is live, you should consider a robust backup plan. Because Paperless-ngx stores critical personal data, losing the media folder would be devastating. Check out our guide on backup strategies for self-hosted servers to automate your data protection.

For more information and advanced configuration, visit the official Paperless-ngx documentation or explore the Paperless-ngx GitHub repository.

Frequently Asked Questions (FAQ)

Can I use Paperless-ngx on a Raspberry Pi?

Yes, Paperless-ngx supports ARM64 architecture. However, because OCR is CPU-intensive, it is recommended to use at least a Raspberry Pi 4 with 4GB of RAM for a smooth experience.

How do I add support for other OCR languages?

In your docker-compose.env file, edit the PAPERLESS_OCR_LANGUAGE variable. You can add multiple languages separated by plus signs, for example: PAPERLESS_OCR_LANGUAGE=eng+deu+fra.

Is my data encrypted at rest?

By default, Paperless-ngx does not encrypt the files stored in the media folder. It relies on the security of the host filesystem. If encryption is required, consider using an encrypted disk partition or a tool like VeraCrypt on the host.

How does the “Consume” folder work?

Paperless-ngx monitors the consume folder for new files. When a file is detected, the system moves it to its internal storage, performs OCR, and indexes the content. Once processed, the file is deleted from the consume folder.