clones/HomelabPaperlessStack
1
0
Fork 0
mirror of https://github.com/timothystewart6/paperless-stack.git synced 2026-07-14 09:08:40 +00:00
Code Issues Projects Releases Packages Wiki Activity
Docker Compose stack for running Paperless-ngx with optional local AI capabilities. https://technotim.com/posts/paperless-ngx-local-ai/
6 commits 1 branch 0 tags 94 KiB
Find a file
Exact
Sebastian Gerhard 53bb08f0f9
 fix: replace docker compose restart with down && up -d in Quick Start (#6) 
* Update restart command for Docker services

In the Quick Start guide, Step 5 instructs users to restart services with: 'docker compose restart'

This command **does not reload environment variables** from `env_file` entries in `docker-compose.yml`. 

This causes paperless-ai to silently fail with `401 Invalid token` and `Failed to get own user ID. 
Abort scanning.` — even though the `.env` file contains the correct values.

This took me 20 Minutes to realise, thus the PR ^^

* fix: replace docker compose restart with down && up -d in Quick Start
2026-07-01 12:10:43 -05:00
dozzle chore(init): Initial commit 2026-01-27 08:58:30 -06:00
gotenberg chore(init): Initial commit 2026-01-27 08:58:30 -06:00
ollama chore(init): Initial commit 2026-01-27 08:58:30 -06:00
open-webui chore(init): Initial commit 2026-01-27 08:58:30 -06:00
paperless chore(init): Initial commit 2026-01-27 08:58:30 -06:00
paperless-ai Fix PAPERLESS_URL formatting in .env file 2026-01-29 13:22:56 +02:00
paperless-gpt chore(init): Initial commit 2026-01-27 08:58:30 -06:00
postgres chore(init): Initial commit 2026-01-27 08:58:30 -06:00
redis chore(init): Initial commit 2026-01-27 08:58:30 -06:00
tika chore(init): Initial commit 2026-01-27 08:58:30 -06:00
compose.yaml chore(init): Initial commit 2026-01-27 08:58:30 -06:00
README.md fix: replace docker compose restart with down && up -d in Quick Start (#6) 2026-07-01 12:10:43 -05:00

README.md

Paperless Stack

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

Quick Start

  1. Clone and configure

    git clone https://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 down && docker compose up -d

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

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:

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