# Papermerge

> Document management system with OCR.

- Category: Storage & Backup
- Difficulty: intermediate
- Components: papermerge, postgres, redis
- Tags: papermerge, documents, ocr, dms
- Source: https://docker.recipes/storage/papermerge

## Overview

Papermerge is an open-source document management system designed to transform paper-based workflows into digital, searchable archives. Built with Django, it provides OCR capabilities to automatically extract text from scanned documents, PDFs, and images, making them fully searchable and organizable through tags, metadata, and folder structures. The system excels at handling invoices, receipts, contracts, and other business documents that need long-term storage and quick retrieval.

This stack combines Papermerge with PostgreSQL and Redis to create a robust document processing pipeline. PostgreSQL serves as the primary database, storing document metadata, user information, and OCR-extracted text with full-text search capabilities. Redis handles background job queuing for OCR processing, caching frequently accessed data, and managing user sessions. When documents are uploaded, Redis queues OCR tasks while PostgreSQL indexes the extracted text for lightning-fast searches across thousands of documents.

Small businesses, accounting firms, legal offices, and home users will find this combination ideal for going paperless. The PostgreSQL backend ensures document metadata integrity and supports complex searches across multiple fields, while Redis accelerates the OCR workflow and improves response times. This setup scales from personal document archives to business-grade document repositories handling thousands of files monthly.

## Features

- Tesseract OCR engine integration for automatic text extraction from scanned PDFs and images
- PostgreSQL full-text search with ranking across document content and metadata
- Redis-powered background job processing for non-blocking OCR operations
- Document versioning and audit trails stored in PostgreSQL with ACID compliance
- Multi-format support including PDF, TIFF, PNG, and JPEG with OCR preprocessing
- Tag-based organization with PostgreSQL foreign key relationships for data integrity
- User permission system with role-based access control backed by PostgreSQL
- Watched folder functionality for automatic document ingestion and OCR processing

## Use cases

- Small business invoice and receipt digitization with automated OCR processing
- Legal document archives requiring full-text search across case files and contracts
- Accounting firm client document management with secure multi-tenant access
- Home office paperless workflow for tax documents, warranties, and personal records
- Medical practice patient file digitization with HIPAA-compliant document storage
- Real estate agencies organizing property documents, contracts, and inspection reports
- HR departments managing employee records, contracts, and compliance documentation

## Prerequisites

- Minimum 2GB RAM (1GB+ for PostgreSQL, 512MB+ for Redis, 512MB+ for Papermerge OCR processing)
- Docker and Docker Compose installed with container runtime support
- Port 12000 available for Papermerge web interface access
- Basic understanding of environment variables and password management
- At least 10GB free disk space for document storage and PostgreSQL data
- Knowledge of PostgreSQL administration for database maintenance and backups

## docker-compose.yml

```yaml
services:
  papermerge:
    image: papermerge/papermerge:latest
    container_name: papermerge
    restart: unless-stopped
    environment:
      PAPERMERGE__SECURITY__SECRET_KEY: ${SECRET_KEY}
      PAPERMERGE__DATABASE__URL: postgresql://papermerge:${DB_PASSWORD}@postgres:5432/papermerge
      PAPERMERGE__REDIS__URL: redis://redis:6379/0
      DJANGO_SUPERUSER_USERNAME: admin
      DJANGO_SUPERUSER_PASSWORD: ${ADMIN_PASSWORD}
    volumes:
      - papermerge_media:/app/media
    ports:
      - "12000:80"
    depends_on:
      - postgres
      - redis
    networks:
      - papermerge

  postgres:
    image: postgres:15-alpine
    container_name: papermerge-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: papermerge
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: papermerge
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - papermerge

  redis:
    image: redis:alpine
    container_name: papermerge-redis
    restart: unless-stopped
    networks:
      - papermerge

volumes:
  papermerge_media:
  postgres_data:

networks:
  papermerge:
    driver: bridge
```

## .env

```bash
SECRET_KEY=changeme-secret-key
DB_PASSWORD=changeme
ADMIN_PASSWORD=changeme
```

## Usage notes

- Docs: https://docs.papermerge.io/
- Access at http://localhost:12000 - login with admin / ADMIN_PASSWORD
- OCR extracts text from scanned PDFs automatically
- Upload PDFs via web UI or watched folders
- Tagging, metadata, full-text search
- Good for digitizing paper documents, invoices, receipts

## Troubleshooting

- OCR processing fails silently: Check Redis connectivity and ensure sufficient memory allocation for Tesseract processing
- Document uploads timeout on large files: Increase Django file upload limits and Redis memory configuration in environment variables
- PostgreSQL connection refused errors: Verify database initialization completed and check POSTGRES_PASSWORD matches PAPERMERGE__DATABASE__URL credentials
- Search results incomplete or missing: Run Django management commands to rebuild PostgreSQL full-text search indexes
- Redis memory usage grows continuously: Configure Redis maxmemory policy and enable key expiration for cached OCR results
- Papermerge container fails to start: Ensure SECRET_KEY environment variable is set and database migration completed successfully

