# Paperless-ngx Document Management

> Document management system with OCR, full-text search, and automatic tagging.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: paperless-ngx, postgresql, redis, gotenberg, tika
- Tags: paperless, document-management, ocr, paperless-ngx
- Source: https://docker.recipes/productivity/paperless-ngx-stack

## Overview

Paperless-ngx is a modern document management system designed to transform physical documents into a searchable digital archive. Originally forked from the now-discontinued Paperless project, Paperless-ngx has evolved into a comprehensive solution that performs optical character recognition (OCR) on scanned documents, automatically extracts metadata, and provides intelligent tagging and classification. The system excels at consuming documents through multiple channels including web uploads, email ingestion, and watched folders. This stack combines Paperless-ngx with PostgreSQL for robust document metadata storage, Redis for caching and task queuing, Gotenberg for PDF generation and conversion, and Apache Tika for advanced document parsing and text extraction. Together, these components create a powerful document processing pipeline that can handle everything from simple scanned receipts to complex multi-page contracts with embedded images and forms. The combination is particularly valuable for organizations and individuals looking to eliminate paper clutter while maintaining full searchability and organization of their document archives. Gotenberg provides reliable PDF rendering capabilities, while Tika's content analysis enhances OCR accuracy and metadata extraction, making this stack suitable for both personal document management and small business applications requiring sophisticated document processing workflows.

## Features

- OCR processing with Tesseract engine supporting 100+ languages
- Full-text search across document contents with highlighting and ranking
- Automatic document classification and tagging based on content patterns
- Email consumption for automatic document import from designated accounts
- Correspondent and tag matching using machine learning algorithms
- Advanced PDF processing via Gotenberg for conversion and generation tasks
- Content analysis and metadata extraction through Apache Tika integration
- Archive format preservation maintaining original file integrity alongside processed versions

## Use cases

- Personal paperless office setup for managing household documents, bills, and receipts
- Small business document archiving with automatic invoice and contract processing
- Home office tax document organization with automatic categorization by year and type
- Legal practice case file management with OCR-searchable document discovery
- Medical office patient record digitization with HIPAA-compliant storage
- Real estate document management for property records and transaction files
- Academic research paper organization with full-text search across literature collections

## Prerequisites

- Docker host with minimum 2GB RAM (4GB+ recommended for OCR processing)
- Available ports 8000 for Paperless-ngx web interface
- 50GB+ storage space for document archive growth and PostgreSQL data
- Basic understanding of document scanning workflows and OCR limitations
- Knowledge of email server configuration if using email consumption features

## docker-compose.yml

```yaml
services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    ports:
      - "8000:8000"
    environment:
      PAPERLESS_REDIS: redis://redis:6379
      PAPERLESS_DBHOST: postgres
      PAPERLESS_DBUSER: ${POSTGRES_USER}
      PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}
      PAPERLESS_DBNAME: ${POSTGRES_DB}
      PAPERLESS_SECRET_KEY: ${SECRET_KEY}
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_OCR_LANGUAGE: eng
      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
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
      gotenberg:
        condition: service_started
      tika:
        condition: service_started
    networks:
      - paperless-net
    restart: unless-stopped

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

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - paperless-net
    restart: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:latest
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"
    networks:
      - paperless-net
    restart: unless-stopped

  tika:
    image: apache/tika:latest
    networks:
      - paperless-net
    restart: unless-stopped

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

networks:
  paperless-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=paperless
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=paperless

# Paperless-ngx
SECRET_KEY=$(openssl rand -hex 32)
ADMIN_USER=admin
ADMIN_PASSWORD=secure_admin_password
```

## Usage notes

- Paperless-ngx at http://localhost:8000
- Drop files in consume folder for auto-import
- OCR processes documents automatically
- Configure mail consumption for email imports

## Troubleshooting

- OCR processing fails with 'Tesseract not found' error: Verify PAPERLESS_OCR_LANGUAGE environment variable matches installed language packs in container
- Documents stuck in 'Processing' status indefinitely: Check Redis container health and restart paperless container to clear task queue
- Gotenberg PDF conversion timeouts: Increase container memory limits and verify --chromium-allow-list permissions for temporary files
- Tika text extraction returns empty results: Ensure document file permissions allow container read access and file format is supported
- PostgreSQL connection refused during startup: Wait for postgres healthcheck to pass before paperless container initialization completes
- Web interface shows 'CSRF token missing' errors: Verify PAPERLESS_SECRET_KEY is set and consistent across container restarts

