> ## 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.

# 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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/lumina-ai-inc/chunkr.git
    cd chunkr
    ```
  </Step>

  <Step title="Configure environment variables">
    Copy the example environment file and configure it:

    ```bash theme={null}
    cp .env.example .env
    ```

    See the [Environment Variables](/deployment/environment-variables) page for detailed configuration options.
  </Step>

  <Step title="Start the services">
    <CodeGroup>
      ```bash GPU (Default) theme={null}
      docker compose up -d
      ```

      ```bash CPU Only theme={null}
      docker compose -f compose.yaml -f compose.cpu.yaml up -d
      ```

      ```bash Mac (Apple Silicon) theme={null}
      docker compose -f compose.yaml -f compose.mac.yaml up -d
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify deployment">
    Check that all services are running:

    ```bash theme={null}
    docker compose ps
    ```

    Access the API at `http://localhost:8000` and the web UI at `http://localhost:5173`.
  </Step>
</Steps>

## 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:

```yaml theme={null}
segmentation-backend:
  deploy:
    replicas: 6
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: all
            capabilities: [gpu]
```

<Info>
  GPU deployment provides significantly faster inference times. See [GPU Setup](/deployment/gpu-setup) for configuration details.
</Info>

### CPU-Only Deployment

For environments without GPU support, use the CPU overlay:

```bash theme={null}
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

<Warning>
  CPU deployment will be slower than GPU. Consider adjusting replica counts based on your CPU cores and workload.
</Warning>

### Mac Deployment (Apple Silicon)

For Mac development environments:

```bash theme={null}
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:

```yaml theme={null}
volumes:
  - ./models.yaml:/app/models.yaml:ro
```

Ensure your `models.yaml` file exists in the root directory before starting services.

## Managing Services

### View Logs

<CodeGroup>
  ```bash All Services theme={null}
  docker compose logs -f
  ```

  ```bash Specific Service theme={null}
  docker compose logs -f server
  ```

  ```bash With Timestamps theme={null}
  docker compose logs -f -t
  ```
</CodeGroup>

### Restart Services

```bash theme={null}
# Restart all services
docker compose restart

# Restart specific service
docker compose restart server
```

### Stop Services

```bash theme={null}
# 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

```bash theme={null}
# 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:

```yaml theme={null}
volumes:
  postgres_data:    # Database data
  redis_data:       # Cache and queue data
  minio_data:       # Document storage
```

<Warning>
  Always backup these volumes before running `docker compose down -v`.
</Warning>

## 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](/deployment/gpu-setup)
3. Ensure drivers are properly installed

## Next Steps

* Configure [Environment Variables](/deployment/environment-variables)
* Set up [GPU acceleration](/deployment/gpu-setup)
* Learn about [Scaling](/deployment/scaling) for production workloads