Research/chunking/docs/adr/0006-qdrant-deployment.md

ADR 0006: Qdrant Deployment

Status

Accepted

Context

The system is migrating from ChromaDB to Qdrant. Deployment must work fully on-premises with no external dependencies, given the risk of prolonged internet blackouts (up to 90 days).

Decision

Deploy Qdrant as a Docker container on-premises.

Configuration

# docker-compose.yml
services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"  # REST API
      - "6334:6334"  # gRPC API
    volumes:
      - ./qdrant_storage:/qdrant/storage
    environment:
      - QDRANT__LOG_LEVEL=INFO
    restart: unless-stopped

Why Docker

• Isolation — consistent environment, no dependency conflicts
• Portability — easy to move between servers
• Simplicity — single container, no orchestration complexity
• Persistence — volume mount ensures data survives container restarts
• No external dependencies — fully on-prem

Collection Configuration

Single collection with named vectors:

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams

client = QdrantClient(host="localhost", port=6333)

client.create_collection(
    collection_name="insurance_docs",
    vectors_config={
        "openai": VectorParams(size=3072, distance=Distance.COSINE),
        "nomic": VectorParams(size=768, distance=Distance.COSINE),
    }
)

Consequences

Positive

• Fully on-prem — works during internet blackouts
• Simple operations — single container to manage
• Fast access — no network latency to external services
• Data sovereignty — all data stays in your infrastructure

Negative

• Manual backups — must implement backup strategy
• Single point of failure — no built-in replication (consider Qdrant cluster if HA needed)
• Hardware dependent — performance tied to host resources

Neutral

• Storage requirements depend on corpus size and vector dimensions
• May need to tune Qdrant's HNSW parameters for optimal recall/speed trade-off
• Consider resource limits in Docker for predictable performance

Backup Strategy

• Regular snapshots: qdrant-cli snapshot create
• Volume backup: backup ./qdrant_storage directory
• Test restore procedure before production deployment

Alternatives Considered

1. Qdrant Cloud — requires internet, not viable
2. Kubernetes deployment — adds complexity, not needed for single-node setup
3. Standalone binary — Docker provides better isolation and process management