# Docspell Document Management

> Personal document organizer with OCR and full-text search.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: docspell-restserver, docspell-joex, solr, postgresql
- Tags: document-management, docspell, ocr, organization, dms
- Source: https://docker.recipes/productivity/docspell-dms

## Overview

Docspell is an open-source personal document management system designed to organize, process, and search through documents using advanced OCR and machine learning capabilities. Built with Scala and developed as a privacy-focused alternative to cloud-based document solutions, Docspell excels at automatically extracting metadata from documents, recognizing correspondents, and categorizing content through intelligent tagging. The system processes various document formats including PDFs, images, and office documents, making them fully searchable and organized.

This deployment creates a complete four-service Docspell environment with the restserver handling the web interface and API operations, joex managing background processing tasks like OCR and document analysis, a PostgreSQL database for metadata storage, and Apache Solr providing powerful full-text search capabilities. The restserver acts as the user-facing component on port 7880, while joex operates behind the scenes to process uploaded documents, extract text through OCR, and perform automated classification tasks.

This configuration is ideal for individuals, small businesses, or teams who need to digitize and organize large volumes of paper documents, automate invoice processing, or create searchable archives of correspondence. The combination of PostgreSQL's robust data integrity with Solr's advanced search features provides both reliable storage and lightning-fast document retrieval, making it particularly valuable for legal offices, accounting firms, or anyone dealing with document-heavy workflows.

## Features

- Advanced OCR processing with automatic text extraction from scanned documents and images
- Machine learning-powered automatic tagging and correspondent recognition
- Full-text search capabilities powered by Apache Solr with highlighting and relevance ranking
- Multi-format document support including PDF, DOCX, images, and email attachments
- Automated document classification with customizable rules and patterns
- RESTful API for integration with external systems and workflow automation
- Multi-user support with role-based access control and organization management
- Background job processing system for handling large document batches without blocking the interface

## Use cases

- Small business invoice and receipt management with automatic vendor recognition
- Legal document archiving with advanced search and metadata extraction
- Personal paperwork organization for tax documents, contracts, and correspondence
- Academic research paper collection with full-text search and citation management
- Real estate document management for property records and transaction history
- Medical practice patient record digitization and HIPAA-compliant storage
- Non-profit organization grant application and compliance document tracking

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for optimal OCR processing
- Port 7880 available for Docspell web interface access
- Environment variables configured for DB_PASSWORD, ADMIN_SECRET, and AUTH_SECRET
- Basic understanding of document management workflows and OCR limitations
- Sufficient disk space for document storage and PostgreSQL/Solr data growth
- Network access for downloading OCR models and language packs during initial setup

## docker-compose.yml

```yaml
services:
  restserver:
    image: docspell/restserver:latest
    container_name: docspell-restserver
    environment:
      - DOCSPELL_SERVER_INTERNAL__URL=http://restserver:7880
      - DOCSPELL_SERVER_ADMIN__ENDPOINT__SECRET=${ADMIN_SECRET}
      - DOCSPELL_SERVER_AUTH__SERVER__SECRET=${AUTH_SECRET}
      - DOCSPELL_SERVER_BACKEND__JDBC__URL=jdbc:postgresql://db:5432/docspell
      - DOCSPELL_SERVER_BACKEND__JDBC__USER=docspell
      - DOCSPELL_SERVER_BACKEND__JDBC__PASSWORD=${DB_PASSWORD}
      - DOCSPELL_SERVER_FULL__TEXT__SEARCH__ENABLED=true
      - DOCSPELL_SERVER_FULL__TEXT__SEARCH__SOLR__URL=http://solr:8983/solr/docspell
    ports:
      - "7880:7880"
    depends_on:
      - db
      - solr
    networks:
      - docspell-network
    restart: unless-stopped

  joex:
    image: docspell/joex:latest
    container_name: docspell-joex
    environment:
      - DOCSPELL_JOEX_APP__ID=joex1
      - DOCSPELL_JOEX_BASE__URL=http://joex:7878
      - DOCSPELL_JOEX_JDBC__URL=jdbc:postgresql://db:5432/docspell
      - DOCSPELL_JOEX_JDBC__USER=docspell
      - DOCSPELL_JOEX_JDBC__PASSWORD=${DB_PASSWORD}
      - DOCSPELL_JOEX_FULL__TEXT__SEARCH__ENABLED=true
      - DOCSPELL_JOEX_FULL__TEXT__SEARCH__SOLR__URL=http://solr:8983/solr/docspell
    depends_on:
      - db
      - solr
    networks:
      - docspell-network
    restart: unless-stopped

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

  solr:
    image: solr:9
    container_name: docspell-solr
    command: solr-precreate docspell
    volumes:
      - solr-data:/var/solr
    networks:
      - docspell-network
    restart: unless-stopped

volumes:
  postgres-data:
  solr-data:

networks:
  docspell-network:
    driver: bridge
```

## .env

```bash
# Docspell
DB_PASSWORD=secure_docspell_password

# Generate with: openssl rand -hex 32
ADMIN_SECRET=your_admin_secret
AUTH_SECRET=your_auth_secret
```

## Usage notes

- Web UI at http://localhost:7880
- Register first account
- OCR for scanned documents
- Full-text search with Solr
- Automatic tagging and organization

## Troubleshooting

- OCR processing fails or produces poor results: Ensure uploaded documents have sufficient resolution (300+ DPI) and check joex container logs for tessaract errors
- Solr search returns no results for existing documents: Verify the Solr core 'docspell' was created properly and check full-text search is enabled in both restserver and joex configurations
- Database connection errors in restserver logs: Confirm PostgreSQL container is fully started and DB_PASSWORD environment variable matches between db and restserver services
- Documents stuck in processing queue: Check joex container resources and restart the joex service, as OCR operations can be memory-intensive
- Login fails after initial setup: Verify ADMIN_SECRET and AUTH_SECRET are properly set and consistent across restarts, check restserver logs for authentication errors
- File uploads fail or timeout: Increase Docker container memory limits and check available disk space in the postgres-data and solr-data volumes

