docs/deployment/docker.md

Docker Deployment

Last Updated: 2025-12-06

This guide covers deploying DeepBoner using Docker.

Quick Start

# Build the image
docker build -t deepboner .

# Run the container
docker run -p 7860:7860 deepboner

Open http://localhost:7860

Dockerfile Overview

The project uses a multi-stage approach:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y git curl

# Install uv package manager
RUN pip install uv==0.5.4

# Copy project files
COPY pyproject.toml uv.lock src/ README.md .

# Install runtime dependencies (no dev tools)
RUN uv sync --frozen --no-dev --extra embeddings --extra magentic

# Create non-root user
RUN useradd --create-home appuser
USER appuser

# Pre-download embedding model
RUN uv run python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

# Expose port and run
EXPOSE 7860
CMD ["uv", "run", "python", "-m", "src.app"]

Building

Basic Build

docker build -t deepboner .

With Build Arguments

# Custom tag
docker build -t deepboner:v0.1.0 .

# No cache (clean build)
docker build --no-cache -t deepboner .

Multi-Platform Build

docker buildx build --platform linux/amd64,linux/arm64 -t deepboner .

Running

Basic Run

docker run -p 7860:7860 deepboner

With Environment Variables

docker run -p 7860:7860 \
  -e OPENAI_API_KEY=sk-your-key \
  -e NCBI_API_KEY=your-ncbi-key \
  -e LOG_LEVEL=INFO \
  deepboner

Using .env File

docker run -p 7860:7860 --env-file .env deepboner

With Persistent Storage

# Persist ChromaDB data
docker run -p 7860:7860 \
  -v $(pwd)/data/chroma:/app/chroma_db \
  deepboner

Detached Mode

docker run -d -p 7860:7860 --name deepboner-app deepboner

Configuration

Environment Variables

Variable	Description	Required
OPENAI_API_KEY	OpenAI API key (premium mode)	No
NCBI_API_KEY	NCBI API key (higher rate limits)	No
HF_TOKEN	HuggingFace token	No
LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	No
MAX_ITERATIONS	Max search iterations (1-50)	No

Ports

Port	Service
7860	Gradio UI + MCP Server

Volumes

Path	Purpose
/app/chroma_db	ChromaDB vector store
/app/.cache	HuggingFace model cache

Health Check

The container includes a health check:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:7860/ || exit 1

Check health status:

docker inspect --format='{{.State.Health.Status}}' deepboner-app

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  deepboner:
    build: .
    ports:
      - "7860:7860"
    environment:
      - LOG_LEVEL=INFO
    env_file:
      - .env
    volumes:
      - chroma_data:/app/chroma_db
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7860/"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  chroma_data:

Run with:

docker-compose up -d

Production Considerations

Resource Limits

docker run -p 7860:7860 \
  --memory=4g \
  --cpus=2 \
  deepboner

Logging

# View logs
docker logs deepboner-app

# Follow logs
docker logs -f deepboner-app

# With timestamps
docker logs -t deepboner-app

Security

The container runs as non-root user (appuser):

RUN useradd --create-home appuser
USER appuser

Do not:

• Expose ports beyond 7860
• Mount sensitive host paths
• Run as root in production

Reverse Proxy

For production, use a reverse proxy (nginx, traefik):

server {
    listen 80;
    server_name deepboner.example.com;

    location / {
        proxy_pass http://localhost:7860;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Troubleshooting

Container exits immediately

Check logs:

docker logs deepboner-app

Common causes:

• Missing environment variables
• Port conflict
• Insufficient memory

Slow startup

First run downloads models. Pre-warm the cache:

# Build includes model download
docker build -t deepboner .

Out of memory

Increase memory limit:

docker run -p 7860:7860 --memory=8g deepboner

Cannot connect to port

Check if port is in use:

lsof -i :7860

Use a different port:

docker run -p 8080:7860 deepboner

Related Documentation

• HuggingFace Spaces Deployment
• MCP Integration
• Configuration Reference