DOCSEARCHbyAlgolia
Submit Docs

Paperless Stack

repository·main·Indexed 41 days ago

https://github.com/timothystewart6/paperless-stack

A Docker Compose stack for a self-hosted document management system using Paperless-ngx. It includes supporting services like Postgres, Redis, Gotenberg, and Tika, with optional local AI capabilities via Ollama, Open WebUI, Paperless-AI, and Paperless-GPT for improved OCR and automated metadata tagging.

Tokens
2.5K
Snippets
8
Records
9
Agent score
3%

What's inside Paperless Stack

  1. Configure optional local AI capabilities

    main

    The AI components (Paperless-AI and Paperless-GPT) are optional. To enable them, follow these steps:

    1. Pull required models: Open Open WebUI at http://localhost:3001 and download:
      • llama3.2:3b (for metadata suggestions and reasoning)
      • minicpm-v:8b (vision model for improved OCR) Note: These model names must match the entries in ./paperless-ai/.env and ./paperless-gpt/.env.
    2. Generate Paperless API Token: In the Paperless web interface, go to Profile → API Tokens → Generate. Copy the resulting token.
    3. Update AI configurations:
      • Add the token to ./paperless-ai/.env and ./paperless-gpt/.env.
      • Add your Paperless username to ./paperless-ai/.env.
    4. Restart the stack to apply changes:
      docker compose down && docker compose up -d
    docker compose down && docker compose up -d

  2. Basic usage and maintenance

    main

    Document Ingestion

    Drop files into the ./paperless/consume/ folder to automatically add them to Paperless.

    Searching

    Use the search bar within the Paperless web interface (http://localhost:8000).

    Logs

    View real-time logs using Dozzle at http://localhost:8080 or via CLI:

    docker compose logs [service-name]

    Backups

    Always back up the following directories to ensure data persistence:

    • ./paperless/data/
    • ./paperless/media/
    • ./postgres/data/

    Updates

    To update the stack to the latest images:

    docker compose pull && docker compose up -d
    docker compose logs [service-name]
docker compose pull && docker compose up -d

  3. Quick Start: Install and run Paperless Stack

    main

    To deploy the Paperless Stack using Docker Compose, follow these steps:

    1. Clone the repository and enter the directory:
      git clone https://github.com/timothystewart6/paperless-stack.git
cd paperless-stack
    2. Configure environment variables: Update the passwords and secrets in the respective .env files. Crucially, ensure the database credentials in ./postgres/.env match the configuration in ./paperless/.env.
    3. Launch the stack:
      docker compose up -d
    4. Initialize Paperless: Navigate to http://localhost:8000 to create your admin account.
    git clone https://github.com/timothystewart6/paperless-stack.git
cd paperless-stack
docker compose up -d

  4. Install and use Dozzle for log viewing

    main

    Dozzle is an optional service used to view real-time logs from your Docker containers via a web interface.

    Access: Port 8080. Requirements: Requires access to the host's Docker socket (/var/run/docker.sock) to retrieve logs. Volumes: ./dozzle/data -> /data.

    services:
  dozzle:
    image: amir20/dozzle:latest
    container_name: dozzle
    env_file: 
      - ./dozzle/.env
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./dozzle/data:/data
    ports:
      - "8080:8080"

  5. Troubleshoot Paperless Stack issues

    main

    If you encounter issues, check the following:

    • Service Status: Run docker compose ps to ensure all containers are running.
    • Logs: Use Dozzle (http://localhost:8080) or docker compose logs [service-name] to inspect errors.
    • Database Connectivity: Verify that the credentials in ./paperless/.env match those in ./postgres/.env.
    • AI Functionality: Ensure the Ollama service is running and that the required models (e.g., llama3.2:3b, minicpm-v:8b) have been successfully pulled in Open WebUI.
    docker compose ps
docker compose logs [service-name]

  6. Configure LLM and AI services

    main

    The stack includes several services for interacting with Large Language Models (LLMs), including local execution via Ollama and web interfaces via Open-WebUI.

    Ollama (Local LLM Engine)

    Runs local models. Supports NVIDIA GPU acceleration.

    • Volumes: ./ollama/data/ (models/data) and ./ollama/models (model storage).
    • GPU Config: Uses driver: nvidia with capabilities: [gpu].

    Open-WebUI

    Provides a web interface for LLM interaction. Depends on ollama.

    • Access: Port 3001.
    • Volumes: ./open-webui/data -> /app/backend/data.

    Paperless-AI & Paperless-GPT

    AI-specific integrations for Paperless-ngx. Both depend on ollama and paperless.

    • Paperless-AI: Access via port 3000. Volume: ./paperless-ai/data.
    • Paperless-GPT: Access via port 3002. Volume: ./paperless-gpt/prompts (used for custom prompts).
    services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:latest
    ports:
      - "3001:8080"
    volumes:
      - ./open-webui/data:/app/backend/data

  ollama:
    image: ollama/ollama:latest
    volumes:
      - ./ollama/data/:/root/.ollama
      - ./ollama/models:/ollama-models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  paperless-ai:
    image: clusterzx/paperless-ai:latest
    ports:
      - "3000:3000"
    volumes:
      - ./paperless-ai/data:/app/data

  paperless-gpt:
    image: icereed/paperless-gpt:latest
    ports:
      - "3002:8080"
    volumes:
      - ./paperless-gpt/prompts:/app/prompts

  7. Configure Paperless-ngx main service

    main

    The paperless service is the core component of the stack. It requires postgres, redis, gotenberg, and tika to function correctly. Configuration is managed via an environment file located at ./paperless/.env.

    Key Volume Mappings:

    • ./paperless/data -> /usr/src/paperless/data (Internal application data)
    • ./paperless/media -> /usr/src/paperless/media (Stored documents/media)
    • ./paperless/export -> /usr/src/paperless/export (Exported data)
    • ./paperless/consume -> /usr/src/paperless/consume (Directory for incoming documents to be processed)

    Access:

    • Default port: 8000
    services:
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    restart: unless-stopped
    env_file: 
      - ./paperless/.env
    depends_on:
      - postgres
      - redis
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - ./paperless/data:/usr/src/paperless/data
      - ./paperless/media:/usr/src/paperless/media
      - ./paperless/export:/usr/src/paperless/export
      - ./paperless/consume:/usr/src/paperless/consume

  8. Access the Paperless Stack services

    main

    Once the stack is running, you can access the various services via the following URLs:

    ServiceURLDescription
    Paperless-ngxhttp://localhost:8000Main document management interface
    Open WebUIhttp://localhost:3001Model management for Ollama
    Paperless-AIhttp://localhost:3000AI metadata suggestions service
    Paperless-GPThttp://localhost:3002Vision-based OCR service
    Dozzlehttp://localhost:8080Real-time log viewer

  9. Configure supporting services for Paperless-ngx

    main

    Paperless-ngx relies on several supporting services for database management, document conversion, and text extraction. Each service uses its own .env file for configuration.

    ServiceImagePurposeKey Volumes
    postgrespostgres:18Database./postgres/data -> /var/lib/postgresql
    redisredis:8Cache/Broker./redis/data -> /data
    gotenberggotenberg:8.25Document ConversionN/A
    tikaapache/tika:latestText ExtractionN/A
    services:
  postgres:
    image: postgres:18
    env_file: 
      - ./postgres/.env
    volumes:
      - ./postgres/data:/var/lib/postgresql

  redis:
    image: docker.io/library/redis:8
    env_file: 
      - ./redis/.env
    volumes:
      - ./redis/data:/data

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.25
    env_file: 
      - ./gotenberg/.env
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:latest
    env_file: ./tika/.env