Paperless Stack

Docker Compose stack for running Paperless-ngx with optional local AI capabilities.

Quick Start

1. Clone and configure

   git clone git@github.com:timothystewart6/paperless-stack.git
   cd paperless-stack

2. Edit environment files

   Update passwords and secrets in each service's .env file:

   • ./paperless/.env - Paperless configuration
   • ./postgres/.env - Database credentials (must match Paperless config)
   • Other service .env files as needed

3. Start the stack

   docker compose up -d

4. Create admin account

   Open http://localhost:8000 and create your Paperless admin account.

5. Optional: Configure AI services

   For AI features, you'll need to:

   • Open Open WebUI at http://localhost:3001 and pull models:
     • llama3.2:3b (lightweight, for metadata suggestions and document reasoning)
     • minicpm-v:8b (vision model, for improved OCR)
     • These should match the models listed in ./paperless-ai/.env and `./paperless-gpt/.env
   • In Paperless, go to Profile → API Tokens → Generate
   • Copy the token and add it to ./paperless-ai/.env and ./paperless-gpt/.env
   • Update ./paperless-ai/.env with Paperless username
   • Restart services: docker compose restart

The AI components are entirely optional and can be disabled by commenting them out. Paperless works great without AI.

Access

Service	URL
Paperless-ngx	http://localhost:8000
Open WebUI	http://localhost:3001
Paperless-AI	http://localhost:3000
Paperless-GPT	http://localhost:3002
Dozzle (logs)	http://localhost:8080

What's Included

• Pre-configured environment files for all services
• Paperless-ngx with OCR, tagging, and search capabilities
• PostgreSQL database and Redis cache
• Document conversion and text extraction (Gotenberg, Tika)
• Optional local AI features:
  • Ollama for local LLM inference
  • Open WebUI for model management
  • Paperless-AI for metadata suggestions
  • Paperless-GPT for vision-based OCR improvements and metadata suggestions
• Log viewer with Dozzle

Basic Usage

• Add documents: Drop files in ./paperless/consume/ folder
• Search documents: Use the search bar in Paperless web interface
• View logs: Use Dozzle at http://localhost:8080

Important Notes

• Security: Use a VPN for remote access. Don't expose these services directly to the internet.
• Backups: Back up ./paperless/data/, ./paperless/media/, and ./postgres/data/
• Updates: Run docker compose pull && docker compose up -d

Resources

• Detailed Guide: Self-Hosted Paperless-ngx + Optional Local AI
• Video Tutorial: Paperless-ngx + Local AI (Optional): Better OCR, Self-Hosted, No Cloud

Troubleshooting

• Check logs: docker compose logs [service-name] or use Dozzle at http://localhost:8080
• Check service status: docker compose ps
• Verify database credentials match between paperless and postgres .env files
• For AI issues, ensure Ollama is running and models are downloaded

For detailed troubleshooting including AI setup, vision OCR, and workflows, see the guide above.

Acknowledgments

This stack is built using these awesome open-source projects:

• Paperless-ngx - Document management system with OCR and search
• Ollama - Local LLM inference
• Open WebUI - Web interface for Ollama
• Paperless-AI - AI-powered metadata suggestions
• Paperless-GPT - Vision OCR for Paperless
• PostgreSQL - Database system
• Redis - Cache and message broker
• Gotenberg - Document conversion API
• Apache Tika - Content detection and extraction
• Dozzle - Real-time log viewer for Docker

Special thanks to the maintainers and contributors of these projects for making self-hosted document management and local AI accessible.