bigRAG
Deployment

Production

Configuration and best practices for production deployments.

Production Docker Compose

services:
  bigrag:
    image: yoginth/bigrag:latest
    ports:
      - "6100:6100"
    volumes:
      - bigrag_data:/data
    environment:
      BIGRAG_DATABASE_URL: postgres://bigrag:strongpassword@postgres:5432/bigrag?sslmode=disable
      BIGRAG_MILVUS_URI: http://milvus:19530
      BIGRAG_REDIS_URL: redis://redis:6379/0
      BIGRAG_API_SECRET: your-api-secret
      BIGRAG_LOG_FORMAT: json
      BIGRAG_UPLOAD_DIR: /data/uploads
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
      milvus:
        condition: service_healthy

  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: bigrag
      POSTGRES_PASSWORD: strongpassword
      POSTGRES_DB: bigrag
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U bigrag"]
      interval: 10s
      timeout: 5s
      retries: 5

  milvus-etcd:
    image: quay.io/coreos/etcd:v3.5.18
    environment:
      ETCD_AUTO_COMPACTION_MODE: revision
      ETCD_AUTO_COMPACTION_RETENTION: "1000"
      ETCD_QUOTA_BACKEND_BYTES: "4294967296"
    volumes:
      - etcd_data:/etcd
    command: >
      etcd
      -advertise-client-urls=http://127.0.0.1:2379
      -listen-client-urls=http://0.0.0.0:2379
      --data-dir=/etcd

  milvus:
    image: milvusdb/milvus:v2.5.4
    command: ["milvus", "run", "standalone"]
    ports:
      - "19530:19530"
    environment:
      ETCD_ENDPOINTS: milvus-etcd:2379
    volumes:
      - milvus_data:/var/lib/milvus
    depends_on:
      - milvus-etcd
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      timeout: 20s
      retries: 3

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  bigrag_data:
  postgres_data:
  etcd_data:
  milvus_data:
  redis_data:
# Security
BIGRAG_API_SECRET=your-api-secret

# Infrastructure
BIGRAG_DATABASE_URL=postgres://user:pass@host:5432/bigrag?sslmode=require
BIGRAG_REDIS_URL=redis://redis:6379/0

# Performance
BIGRAG_WORKERS=8                    # Match CPU cores
BIGRAG_INGESTION_WORKERS=8          # More workers for heavy ingestion
BIGRAG_DB_POOL_MAX=100              # Increase for high concurrency
BIGRAG_EMBEDDING_CONCURRENCY=16     # Parallel embedding requests
BIGRAG_MILVUS_MAX_WORKERS=64        # Milvus thread pool

# Logging
BIGRAG_LOG_FORMAT=json              # Structured logging

# Storage (S3 for production)
BIGRAG_STORAGE_BACKEND=s3
BIGRAG_S3_BUCKET=your-bucket
BIGRAG_S3_REGION=us-east-1

Storage Backends

Local Storage (default)

Files stored on the local filesystem:

[storage]
backend = "local"

[ingestion]
upload_dir = "./data/uploads"

S3 Storage

Files stored in an S3-compatible bucket (AWS S3, MinIO, etc.):

[storage]
backend = "s3"

[s3]
bucket = "my-bigrag-bucket"
endpoint_url = "https://s3.amazonaws.com"
region = "us-east-1"
access_key = "AKIA..."
secret_key = "..."

For production, use S3 storage to separate compute from storage and enable horizontal scaling.

Logging

# Development (colorized text)
BIGRAG_LOG_LEVEL=debug BIGRAG_LOG_FORMAT=text

# Production (structured JSON)
BIGRAG_LOG_LEVEL=info BIGRAG_LOG_FORMAT=json

Troubleshooting

Connection refused on startup

Ensure all infrastructure services are running and healthy:

docker exec bigrag-postgres pg_isready -U bigrag
curl -f http://localhost:9091/healthz
docker exec bigrag-redis redis-cli ping

Documents stuck in "pending"

  • Verify Redis is running and accessible
  • Check backend logs for worker errors
  • Ensure BIGRAG_INGESTION_WORKERS is > 0

Dimension mismatch on query

The query embedding dimension doesn't match the collection's configured dimension. Ensure you're querying with the same embedding model.

File upload returns 413

File exceeds the max upload size. Increase BIGRAG_MAX_UPLOAD_SIZE_MB.

Slow embedding performance

  • Increase BIGRAG_INGESTION_BATCH_SIZE for better throughput
  • Increase BIGRAG_EMBEDDING_CONCURRENCY for more parallelism

On this page