# Paperless-ngx

> Document management system with OCR.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: paperless, postgres, redis
- Tags: paperless, documents, ocr, archive
- Source: https://docker.recipes/productivity/paperless-ngx

## Overview

Paperless-ngx is a modern document management system designed to digitize and organize physical documents through optical character recognition (OCR) and intelligent indexing. Born from the original Paperless project, paperless-ngx adds enhanced features like improved OCR processing, machine learning-based document classification, and a polished web interface that makes going paperless accessible to both home users and small offices. The system transforms scanned documents and PDFs into a searchable digital archive with automatic tagging and metadata extraction.

This Docker stack combines paperless-ngx with PostgreSQL and Redis to create a robust document management platform. PostgreSQL serves as the primary database, storing document metadata, tags, correspondents, and full-text search indexes with ACID compliance and advanced querying capabilities. Redis acts as both a caching layer for improved web interface performance and a task queue for background OCR processing, ensuring responsive user interactions even during heavy document processing workloads.

This configuration is ideal for individuals transitioning to paperless workflows, small businesses needing document archival solutions, and home lab enthusiasts wanting to organize years of accumulated paperwork. The stack provides enterprise-grade document management capabilities without the complexity and cost of commercial solutions, offering features like email document consumption, mobile access, and API integration for custom workflows.

## Features

- Tesseract OCR engine with multiple language support for text extraction from scanned documents
- Machine learning-powered document classification and automatic tagging based on content patterns
- Full-text search across document contents with PostgreSQL's advanced text search capabilities
- Email consumption for automatic document import from configured email accounts
- Correspondent and document type auto-detection using configurable matching rules
- Web-based document viewer with annotation support and mobile-responsive interface
- Bulk document processing with Redis-powered background task queuing
- REST API for integration with external systems and custom automation workflows

## Use cases

- Home office digitization for tax documents, receipts, and important paperwork organization
- Small business invoice and contract management with automatic vendor recognition
- Legal practice document archival with full-text search across case files and correspondence
- Property management company tenant file organization and lease document tracking
- Medical office patient record digitization with HIPAA-compliant local storage
- Academic research paper organization with automatic citation and author extraction
- Personal finance management with receipt scanning and expense categorization

## Prerequisites

- Minimum 1GB RAM for OCR processing and PostgreSQL operations (2GB+ recommended for heavy usage)
- At least 10GB free disk space for document storage and database growth
- Port 8000 available for paperless-ngx web interface access
- Understanding of document scanning workflows and file organization concepts
- Basic knowledge of environment variable configuration for database credentials
- Scanner or mobile app capability for document digitization input

## docker-compose.yml

```yaml
services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    environment:
      PAPERLESS_REDIS: redis://redis:6379
      PAPERLESS_DBHOST: postgres
      PAPERLESS_DBNAME: ${DB_NAME}
      PAPERLESS_DBUSER: ${DB_USER}
      PAPERLESS_DBPASS: ${DB_PASSWORD}
      PAPERLESS_ADMIN_USER: ${ADMIN_USER}
      PAPERLESS_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    volumes:
      - paperless_data:/usr/src/paperless/data
      - paperless_media:/usr/src/paperless/media
      - paperless_export:/usr/src/paperless/export
      - paperless_consume:/usr/src/paperless/consume
    ports:
      - "8000:8000"
    depends_on:
      - postgres
      - redis
    networks:
      - paperless

  postgres:
    image: postgres:16-alpine
    container_name: paperless-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - paperless

  redis:
    image: redis:alpine
    container_name: paperless-redis
    networks:
      - paperless

volumes:
  paperless_data:
  paperless_media:
  paperless_export:
  paperless_consume:
  postgres_data:

networks:
  paperless:
    driver: bridge
```

## .env

```bash
DB_NAME=paperless
DB_USER=paperless
DB_PASSWORD=changeme
ADMIN_USER=admin
ADMIN_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.paperless-ngx.com/
- Access at http://localhost:8000 - login with ADMIN_USER/ADMIN_PASSWORD
- Drop/scan files into consume folder for automatic import
- OCR extracts text from scanned documents (Tesseract)
- Auto-tagging, correspondent detection, document type classification
- Mobile app available; email import supported

## Troubleshooting

- OCR processing stuck or failing: Verify sufficient memory allocation and check Redis connectivity for task queue operations
- Documents not appearing after upload: Check consume folder permissions and monitor paperless container logs for processing errors
- PostgreSQL connection refused: Ensure database container is fully initialized before paperless-ngx starts, add healthcheck dependencies
- Slow document search performance: Monitor PostgreSQL memory usage and consider increasing shared_buffers for better full-text search caching
- Email consumption not working: Verify email server credentials and check firewall rules for IMAP/POP3 connectivity
- Web interface loading slowly: Check Redis memory usage and restart redis container if memory is exhausted from caching

