Docker Compose Deployment

Deploy Chunkr using Docker Compose for production environments

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

   GPU (Default)

   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:

Service	Port	Description
server	8000	Main API server handling requests
task	-	Background task workers (30 replicas)
web	5173	Web UI interface
segmentation	8001	Document segmentation service with nginx load balancer
segmentation-backend	-	Segmentation model workers (6 replicas)
ocr	8002	OCR service with nginx load balancer
ocr-backend	-	OCR model workers (3 replicas)
postgres	5432	PostgreSQL database
redis	6379	Redis for task queue and caching
minio	9000, 9001	S3-compatible object storage
keycloak	8080	Authentication and authorization
adminer	8082	Database 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

All Services

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

• Configure Environment Variables
• Set up GPU acceleration
• Learn about Scaling for production workloads