Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lumina-ai-inc/chunkr/llms.txt

Use this file to discover all available pages before exploring further.

Chunkr can be deployed using Docker Compose with support for both GPU and CPU configurations. This guide covers the complete deployment process.

​
Prerequisites

Before deploying Chunkr, ensure you have:
  • Docker Engine 20.10 or later
  • Docker Compose V2
  • For GPU deployment: NVIDIA Docker runtime and compatible GPU
  • At least 16GB of RAM (32GB+ recommended for production)
  • Sufficient disk space for models and data storage

​
Quick Start

1

Clone the repository

git clone https://github.com/lumina-ai-inc/chunkr.git
cd chunkr
2

Configure environment variables

Copy the example environment file and configure it:
cp .env.example .env
See the Environment Variables page for detailed configuration options.
3

Start the services

docker compose up -d
4

Verify deployment

Check that all services are running:
docker compose ps
Access the API at http://localhost:8000 and the web UI at http://localhost:5173.

​
Service Architecture

Chunkr deploys the following services:
ServicePortDescription
server8000Main API server handling requests
task-Background task workers (30 replicas)
web5173Web UI interface
segmentation8001Document segmentation service with nginx load balancer
segmentation-backend-Segmentation model workers (6 replicas)
ocr8002OCR service with nginx load balancer
ocr-backend-OCR model workers (3 replicas)
postgres5432PostgreSQL database
redis6379Redis for task queue and caching
minio9000, 9001S3-compatible object storage
keycloak8080Authentication and authorization
adminer8082Database management interface

​
Deployment Configurations

​
GPU Deployment (Default)

The default compose.yaml is optimized for GPU acceleration: 
segmentation-backend:
  deploy:
    replicas: 6
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: all
            capabilities: [gpu]
GPU deployment provides significantly faster inference times. See GPU Setup for configuration details.

​
CPU-Only Deployment

For environments without GPU support, use the CPU overlay: 
docker compose -f compose.yaml -f compose.cpu.yaml up -d
The CPU configuration:
  • Reduces task workers from 30 to 10 replicas
  • Uses optimized CPU threading settings
  • Employs smaller model variants for OCR
  • Adjusts batch sizes for CPU performance
CPU deployment will be slower than GPU. Consider adjusting replica counts based on your CPU cores and workload.

​
Mac Deployment (Apple Silicon)

For Mac development environments: 
docker compose -f compose.yaml -f compose.mac.yaml up -d
This sets platform-specific settings for compatibility with Apple Silicon and Intel Macs.

​
Model Configuration

Chunkr uses a models.yaml file to configure LLM models. This file is mounted as a read-only volume: 
volumes:
  - ./models.yaml:/app/models.yaml:ro
Ensure your models.yaml file exists in the root directory before starting services.

​
Managing Services

​
View Logs

docker compose logs -f

​
Restart Services

# Restart all services
docker compose restart

# Restart specific service
docker compose restart server

​
Stop Services

# Stop without removing containers
docker compose stop

# Stop and remove containers
docker compose down

# Stop and remove volumes (deletes all data)
docker compose down -v

​
Update Services

# Pull latest images
docker compose pull

# Rebuild and restart
docker compose up -d --build

​
Health Checks

Several services include health checks to ensure proper startup:
  • PostgreSQL: Checks database readiness every 10s
  • Redis: Pings Redis every 10s
  • MinIO: Checks storage health every 30s
  • Keycloak: Verifies auth service every 30s with 10-minute startup period

​
Persistent Data

The following volumes persist data across container restarts: 
volumes:
  postgres_data:    # Database data
  redis_data:       # Cache and queue data
  minio_data:       # Document storage
Always backup these volumes before running docker compose down -v.

​
Troubleshooting

​
Services won’t start

  1. Check Docker daemon is running
  2. Verify port availability (8000, 5173, 5432, 6379, 9000, 8080)
  3. Review logs: docker compose logs

​
Out of memory errors

  1. Reduce replica counts in compose.yaml
  2. Increase Docker memory limits
  3. Consider CPU-only deployment for lower memory usage

​
GPU not detected

  1. Verify NVIDIA Docker runtime: docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
  2. Check GPU configuration in GPU Setup
  3. Ensure drivers are properly installed

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us