# Paperless-ngx + PostgreSQL + Redis + Gotenberg

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

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

## Overview

Paperless-ngx is a modern document management system that transforms physical documents into a searchable digital archive through OCR (Optical Character Recognition) and intelligent classification. Originally forked from the paperless project, paperless-ngx adds enhanced features like improved OCR accuracy, automatic document tagging, and mobile-friendly interfaces for managing everything from receipts to legal documents. This stack combines paperless-ngx with PostgreSQL for robust document metadata storage, Redis for high-performance caching and task queuing, Gotenberg for PDF conversion and rendering, and Apache Tika for advanced document parsing and text extraction. Together, these components create a comprehensive document processing pipeline that can handle various file formats, perform OCR on scanned images, extract metadata, and provide full-text search capabilities across your entire document archive. This configuration is ideal for individuals and organizations looking to digitize their paper workflow, create searchable document archives, or implement a lightweight document management system without the complexity of enterprise-grade solutions like SharePoint or Alfresco.

## Features

- OCR processing with Tesseract engine for converting scanned documents to searchable text
- Advanced document parsing through Apache Tika supporting 1000+ file formats including PDFs, Office documents, and images
- PDF generation and manipulation via Gotenberg for consistent document rendering and conversion
- Full-text search with PostgreSQL's advanced search capabilities and ranking algorithms
- Automatic document classification using machine learning to suggest tags and correspondents
- Redis-powered background task processing for OCR, parsing, and indexing operations
- Email consumption for automatically importing documents sent to designated email addresses
- Mobile document scanning integration with smartphone apps for instant digitization

## Use cases

- Home office paperless transformation for receipts, bills, tax documents, and personal records
- Small business document archival with automatic invoice processing and vendor correspondence tracking
- Legal practice case file digitization with full-text search across contracts and legal documents
- Healthcare clinic patient record management with HIPAA-compliant document storage and retrieval
- Educational institution student record keeping and administrative document management
- Non-profit organization grant documentation and compliance record maintenance
- Real estate office property document management for contracts, inspections, and client files

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for OCR processing
- 4GB+ free disk space for document storage, OCR processing temporary files, and database growth
- Port 8000 available for paperless-ngx web interface access
- Basic understanding of environment variables for configuring database credentials and OCR languages
- Familiarity with document scanning workflows and file organization principles
- SSL certificate setup knowledge if exposing the interface over HTTPS to external networks

## docker-compose.yml

```yaml
services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    environment:
      - PAPERLESS_REDIS=redis://redis:6379
      - PAPERLESS_DBHOST=postgres
      - PAPERLESS_DBNAME=paperless
      - PAPERLESS_DBUSER=${POSTGRES_USER}
      - PAPERLESS_DBPASS=${POSTGRES_PASSWORD}
      - PAPERLESS_TIKA_ENABLED=1
      - PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000
      - PAPERLESS_TIKA_ENDPOINT=http://tika:9998
      - PAPERLESS_SECRET_KEY=${SECRET_KEY}
      - PAPERLESS_OCR_LANGUAGE=eng
      - PAPERLESS_TIME_ZONE=UTC
      - 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
      - gotenberg
      - tika
    networks:
      - paperless-network
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=paperless
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - paperless-network
    restart: unless-stopped

  redis:
    image: redis:alpine
    volumes:
      - redis-data:/data
    networks:
      - paperless-network
    restart: unless-stopped

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

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

volumes:
  paperless-data:
  paperless-media:
  paperless-export:
  paperless-consume:
  postgres-data:
  redis-data:

networks:
  paperless-network:
    driver: bridge
```

## .env

```bash
# Paperless-ngx
POSTGRES_USER=paperless
POSTGRES_PASSWORD=secure_postgres_password
SECRET_KEY=your-very-long-secret-key
ADMIN_USER=admin
ADMIN_PASSWORD=secure_admin_password
```

## Usage notes

- Web UI at http://localhost:8000
- Drop files in consume folder
- OCR and text extraction
- Full-text search
- Mobile scanner integration

## Troubleshooting

- OCR processing fails with 'Tesseract not found' error: Ensure the paperless-ngx image includes Tesseract by using the full image tag, not the slim variant
- Documents stuck in 'Processing' status indefinitely: Check Redis connectivity and restart the Redis container to clear stuck background tasks
- Gotenberg service returns 503 errors during PDF conversion: Increase Gotenberg memory limits and disable JavaScript processing for better stability
- PostgreSQL connection refused during startup: Verify POSTGRES_USER and POSTGRES_PASSWORD environment variables match between paperless and postgres services
- Tika service crashes with OutOfMemoryError: Add memory limits to the Tika container using deploy.resources.limits.memory in the compose file
- Paperless web interface shows 'Secret key not configured' error: Generate and set a secure PAPERLESS_SECRET_KEY environment variable with at least 50 random characters

