Paperless-ngx Setup Guide: Go Paperless in 2025

Are you drowning in paper documents? Bills, receipts, tax forms, and important correspondence piling up in filing cabinets? There's a better way. Paperless-ngx is the ultimate self-hosted document management system that transforms your chaotic paper archive into a searchable, organized digital library—all running on your low-power home server.

In this comprehensive guide, we'll walk you through setting up Paperless-ngx with Docker Compose, configuring OCR for automatic text recognition, integrating your scanner, and optimizing everything for a low-power home server setup.

Why Choose Paperless-ngx?

Paperless-ngx is the actively maintained fork of the original Paperless project, featuring a modern web interface and powerful automation capabilities. Here's why it's the go-to choice for self-hosters in 2025:

Key Features

• Automatic OCR: Converts scanned documents into searchable PDFs using Tesseract
• Smart Tagging: AI-powered automatic tagging and correspondent detection
• Full-Text Search: Find any document instantly with powerful search
• Mobile-Friendly: Responsive web UI works great on phones and tablets
• Consumption Automation: Drop files in a folder, and they're automatically processed
• Multi-Language OCR: Support for 100+ languages out of the box
• Low Resource Usage: Runs efficiently on Intel N100, Raspberry Pi 4, and similar hardware

Paperless-ngx vs Cloud Solutions

Hardware Requirements

Paperless-ngx is remarkably efficient. Here's what you need:

Minimum Specs (Small Archive <10,000 docs)

• CPU: Any x86_64 or ARM64 processor
• RAM: 2GB (4GB recommended)
• Storage: 50GB SSD for documents + database

Recommended Specs (Large Archive >10,000 docs)

• CPU: Intel N100 or equivalent (for faster OCR)
• RAM: 8GB
• Storage: 256GB+ SSD with RAID for redundancy

Power Consumption

On an Intel N100 mini PC, expect:

• Idle: 6-8W
• During OCR processing: 15-20W
• Monthly cost: ~$1-2 at average electricity rates

Docker Compose Setup

Let's set up Paperless-ngx with all the bells and whistles. This configuration includes PostgreSQL for the database, Redis for task queuing, and Gotenberg/Tika for enhanced document processing.

Prerequisites

1. Docker and Docker Compose installed
2. A directory for your documents (we'll use /opt/paperless)
3. Basic understanding of Docker networking

Complete Docker Compose Configuration

Create a docker-compose.yml file:

version: "3.8"

services:
  broker:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - paperless

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

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

  tika:
    image: ghcr.io/paperless-ngx/tika:latest
    container_name: paperless-tika
    restart: unless-stopped
    networks:
      - paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: ${POSTGRES_PASSWORD:-changeme}
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_URL: ${PAPERLESS_URL:-http://localhost:8000}
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY:-change-me-to-a-long-random-string}
      PAPERLESS_TIME_ZONE: ${TZ:-America/New_York}
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_ADMIN_USER: ${ADMIN_USER:-admin}
      PAPERLESS_ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin}
    networks:
      - paperless

volumes:
  data:
  media:
  postgres_data:
  redis_data:

networks:
  paperless:
    driver: bridge

Environment Configuration

Create a .env file in the same directory:

# Database
POSTGRES_PASSWORD=your-secure-password-here

# Paperless Settings
PAPERLESS_SECRET_KEY=generate-a-64-char-random-string
PAPERLESS_URL=https://paperless.yourdomain.com
TZ=America/New_York

# Admin Account
ADMIN_USER=admin
ADMIN_PASSWORD=your-admin-password

# OCR Language (comma-separated for multiple)
# PAPERLESS_OCR_LANGUAGE=eng+deu+fra

Launch the Stack

# Create directories
mkdir -p consume export

# Start all services
docker compose up -d

# Check logs
docker compose logs -f webserver

Wait 2-3 minutes for initial setup, then access Paperless at http://your-server-ip:8000.

OCR Configuration

OCR (Optical Character Recognition) is what makes Paperless-ngx truly powerful. Let's optimize it for your needs.

Language Configuration

Add languages to your docker-compose.yml:

environment:
  # Single language
  PAPERLESS_OCR_LANGUAGE: eng
  
  # Multiple languages (use + separator)
  # PAPERLESS_OCR_LANGUAGE: eng+deu+fra+chi_sim

Available language codes include:

• eng - English
• deu - German
• fra - French
• spa - Spanish
• chi_sim - Simplified Chinese
• chi_tra - Traditional Chinese
• jpn - Japanese
• kor - Korean

OCR Modes

Paperless-ngx offers different OCR modes:

environment:
  # Skip OCR if document already has text
  PAPERLESS_OCR_MODE: skip
  
  # OCR everything, even if text exists
  # PAPERLESS_OCR_MODE: redo
  
  # Force OCR, discard existing text
  # PAPERLESS_OCR_MODE: force
  
  # Skip OCR entirely (not recommended)
  # PAPERLESS_OCR_MODE: skip_noarchive

Recommendation: Use skip mode for mixed archives (scanned + digital PDFs). It saves processing time on documents that already contain searchable text.

OCR Quality Settings

Fine-tune OCR quality vs. speed:

environment:
  # Higher values = better quality, slower processing
  PAPERLESS_OCR_DESKEW: true
  PAPERLESS_OCR_ROTATE_PAGES: true
  PAPERLESS_OCR_ROTATE_PAGES_THRESHOLD: 12
  PAPERLESS_OCR_OUTPUT_TYPE: pdfa
  PAPERLESS_OCR_CLEAN: clean

Scanner Integration

The magic of Paperless-ngx happens when you connect a document scanner. Here are the best approaches:

Recommended Scanners for Home Use

Budget Option (~$300):

• Brother ADS-1700W: Wireless, compact, 25 ppm, direct folder scanning
• Ideal for occasional use, excellent mobile app

Mid-Range (~$450):

• Fujitsu ScanSnap iX1400: Fast (40 ppm), reliable, excellent driver support
• Best for regular scanning, handles mixed document sizes well

Premium (~$600):

• Fujitsu ScanSnap iX1600: Wi-Fi + USB, touchscreen, 40 ppm
• Auto-feeds up to 50 sheets, best for high-volume digitization

Scanner Configuration Workflow

Most scanners can save directly to a network folder. Set up the consume folder:

# Create SMB share for scanner access
# Add to /etc/samba/smb.conf:
[paperless]
   path = /opt/paperless/consume
   browseable = yes
   read only = no
   guest ok = yes
   create mask = 0644
   directory mask = 0755

Configure your scanner to:

1. Save as PDF (not image)
2. Resolution: 300 DPI (sweet spot for OCR quality vs. file size)
3. Color mode: Auto-detect or Color
4. Destination: \\your-server-ip\paperless

Mobile Scanning Options

Don't have a dedicated scanner? Use your phone:

• iOS: Files app → Scan Documents → Save to Paperless consume folder via SMB
• Android: Adobe Scan, Microsoft Lens → Export to network folder
• Cross-platform: Paperless-ngx mobile app (unofficial but excellent)

Low-Power Server Optimization

Running Paperless-ngx on an Intel N100 or similar low-power hardware? Here's how to optimize:

Memory Management

Reduce memory footprint with these settings:

environment:
  # Reduce web workers for low-RAM systems
  PAPERLESS_WEBSERVER_WORKERS: 1
  
  # Disable NLTK (natural language processing) if not needed
  PAPERLESS_ENABLE_NLTK: false
  
  # Limit concurrent OCR tasks
  PAPERLESS_TASK_WORKERS: 1
  
  # Reduce thumbnail generation workers
  PAPERLESS_THREADS_PER_WORKER: 1

Database Optimization

For PostgreSQL on low-power systems:

db:
  image: postgres:15
  command: 
    - "postgres"
    - "-c"
    - "shared_buffers=128MB"
    - "-c"
    - "effective_cache_size=256MB"
    - "-c"
    - "work_mem=4MB"

Storage Recommendations

• OS + Docker: 64GB SSD minimum
• Documents: Separate drive/partition for media
• Database: Keep on SSD for fast searches

Example mount structure:

volumes:
  - /mnt/ssd/paperless/data:/usr/src/paperless/data
  - /mnt/hdd/paperless/media:/usr/src/paperless/media

Automatic Tagging and Organization

Paperless-ngx can automatically organize documents using matching algorithms.

Setting Up Auto-Tagging

1. Create Tags in Settings → Tags:

   • bills, receipts, taxes, medical, contracts

2. Configure Matching for each tag:

   • Matching algorithm: Auto (uses machine learning)
   • Or use Regular Expression for precise control

3. Create Correspondents for frequent senders:

   • Match by: Company name, email domain, or regex
   • Example: amazon|amzn → Correspondent "Amazon"

Document Types

Set up document types for better organization:

• Invoice
• Receipt
• Contract
• Letter
• Manual
• Certificate

Example Matching Rules

Tag: bills
Match: (electric|water|gas|utility|billing)
Algorithm: Regular Expression

Correspondent: Insurance Company
Match: (geico|state farm|allstate|progressive)
Algorithm: Regular Expression (case insensitive)

Backup Strategy

Your digital archive needs protection. Here's a solid backup approach:

Automated Backups

Add a backup service to your stack:

services:
  backup:
    image: offen/docker-volume-backup:latest
    container_name: paperless-backup
    restart: unless-stopped
    environment:
      BACKUP_CRON_EXPRESSION: "0 3 * * *"
      BACKUP_FILENAME: "paperless-backup-%Y%m%d.tar.gz"
      BACKUP_RETENTION_DAYS: 30
    volumes:
      - data:/backup/data:ro
      - media:/backup/media:ro
      - postgres_data:/backup/postgres:ro
      - /opt/backups/paperless:/archive

Backup Checklist

• Database (PostgreSQL data)
• Media folder (original documents)
• Data folder (thumbnails, search index)
• docker-compose.yml and .env files
• Export folder (if used)

Restore Process

# Stop services
docker compose down

# Restore volumes from backup
tar -xzf paperless-backup-YYYYMMDD.tar.gz -C /

# Restart services
docker compose up -d

# Rebuild search index if needed
docker compose exec webserver document_index reindex

Common Issues and Solutions

OCR Not Working

Symptoms: Documents imported but text not searchable

Solutions:

1. Check Tika and Gotenberg are running: docker compose ps
2. Verify language pack: Add needed language to PAPERLESS_OCR_LANGUAGE
3. Check logs: docker compose logs webserver | grep -i ocr

Slow Performance

Symptoms: Web UI laggy, documents take forever to process

Solutions:

1. Reduce PAPERLESS_TASK_WORKERS to 1
2. Disable NLTK if not using auto-matching
3. Add more RAM or use SSD for database
4. Check for runaway processes: docker stats

Scanner Connection Issues

Symptoms: Scanner can't reach consume folder

Solutions:

1. Verify SMB share is accessible from scanner's network
2. Check firewall rules (ports 139, 445)
3. Test with: smbclient //server-ip/paperless -U guest -N

Documents Not Being Consumed

Symptoms: Files sit in consume folder indefinitely

Solutions:

1. Check folder permissions: ls -la consume/
2. Verify container can access folder: docker compose exec webserver ls -la /usr/src/paperless/consume
3. Check webserver logs for errors

Cost Breakdown

Budget Setup (~$200)

• Used Intel N100 mini PC: $150
• 256GB SSD: $25
• 2TB HDD for media: $50
• Power cost: ~$12/year

Recommended Setup (~$400)

• Intel N100 mini PC (new): $200
• 512GB NVMe SSD: $50
• 4TB HDD for media: $90
• USB scanner (Brother ADS-1200): $200
• Power cost: ~$15/year

Premium Setup (~$800)

• Intel N100/N305 mini PC: $300
• 1TB NVMe SSD: $80
• 8TB HDD array: $200
• Fujitsu ScanSnap iX1600: $450
• UPS battery backup: $100
• Power cost: ~$20/year

Conclusion

Paperless-ngx transforms document management from a chore into a seamless, automated system. With intelligent OCR, automatic tagging, and powerful search, you'll never lose a document again. Running on a low-power home server, the entire system costs less than $2/month in electricity while providing enterprise-grade document management.

Key Takeaways:

• Full control over your documents—no cloud subscription required
• Powerful OCR makes every document instantly searchable
• Automation handles filing, tagging, and organization
• Low power operation costs almost nothing to run 24/7
• Future-proof your archive with open formats and easy backups

Ready to go paperless? Start with the Docker Compose setup above, connect your scanner, and watch as your paper chaos transforms into an organized, searchable archive.

Additional Resources

• Official Paperless-ngx Documentation
• Paperless-ngx GitHub Repository
• r/selfhosted Paperless Discussions
• Docker Hub - Paperless-ngx