Docker Deployment

BioAgents provides pre-configured Docker setups for both development and production deployments.

Quick Start

Prerequisites

Docker 20.10+
Docker Compose 2.0+
.env file with required credentials

Clone and Configure

Clone Repository

git clone https://github.com/bio-xyz/bioagents-agentkit.git
cd bioagents-agentkit

Configure Environment

cp .env.example .env
nano .env  # Edit with your credentials

Required variables:

OPENAI_API_KEY - Your OpenAI API key
SUPABASE_URL - Supabase project URL
SUPABASE_ANON_KEY - Supabase anon key

Start Services

docker compose up -d

Verify Deployment

curl http://localhost:3000/api/health

Dockerfile

The BioAgents Dockerfile is optimized for production deployments:

FROM oven/bun:latest AS base
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
  ca-certificates \
  texlive-latex-base \
  texlive-latex-extra \
  texlive-fonts-recommended \
  texlive-bibtex-extra \
  texlive-xetex \
  latexmk \
  pandoc \
  lmodern \
  fonts-linuxlibertine \
  && rm -rf /var/lib/apt/lists/*

# Install Supabase CLI
ADD https://github.com/supabase/cli/releases/latest/download/supabase_linux_amd64.tar.gz /tmp/supabase.tar.gz
RUN tar -xzf /tmp/supabase.tar.gz -C /usr/local/bin/ && \
    chmod +x /usr/local/bin/supabase && \
    rm /tmp/supabase.tar.gz

# Install dependencies
COPY package.json bun.lock* ./
RUN bun install

# Copy source and build
COPY . .
RUN cd client && bun run build
RUN bun install --production

# Expose port and run
EXPOSE 3000
ENV NODE_ENV=production
USER bun

CMD ["bun", "run", "src/index.ts"]

The Dockerfile includes LaTeX and Pandoc for paper generation features. These add ~500MB to the image size.

Docker Compose Configurations

Production (API + Worker + Redis)

The default docker-compose.yml deploys a complete production stack:

services:
  # Database migrations
  migrate:
    build: .
    container_name: bioagents-migrate
    env_file:
      - .env
    volumes:
      - supabase_tmp:/app/supabase/.temp
    command: >
      sh -lc '
        set -eu
        mkdir -p /app/supabase/.temp
        supabase db push --db-url "$SUPABASE_FULL_URL"
      '
    restart: "no"

  # API Server
  bioagents:
    build: .
    container_name: bioagents-api
    expose:
      - "${PORT:-3000}"
    ports:
      - "${PORT:-3000}:3000"
    volumes:
      - bioagents-docs:/app/docs
      - bioagents-images:/app/client/public/images
    environment:
      - USE_JOB_QUEUE=true
      - REDIS_URL=redis://redis:6379
      - PORT=3000
      - HOST=0.0.0.0
      - NODE_ENV=production
    env_file:
      - .env
    restart: unless-stopped
    healthcheck:
      test:
        [
          "CMD",
          "bun",
          "run",
          "-e",
          "fetch('http://localhost:3000/api/health').then(r => r.ok ? process.exit(0) : process.exit(1))",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # Redis
  redis:
    image: redis:7-alpine
    container_name: bioagents-redis
    command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy noeviction
    volumes:
      - redis-data:/data
    ports:
      - "${REDIS_PORT:-6379}:6379"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  supabase_tmp:
  bioagents-docs:
  bioagents-images:
  redis-data:

Key Features

Database Migrations

The migrate service runs Supabase database migrations on startup using the Supabase CLI.

# Manually run migrations
docker compose run --rm migrate

Persistent Volumes

bioagents-docs - RAG knowledge documents
bioagents-images - Generated figure images
redis-data - Job queue persistence
supabase_tmp - Migration temp files

Health Checks

API server: HTTP GET /api/health every 30s
Redis: redis-cli ping every 10s
Worker: process check via pgrep

Common Commands

Start Services

# Start all services in background
docker compose up -d

# Start with build (after code changes)
docker compose up -d --build

# Start specific service
docker compose up -d bioagents

View Logs

# Follow all logs
docker compose logs -f

# Follow specific service
docker compose logs -f bioagents
docker compose logs -f worker
docker compose logs -f redis

# Last 100 lines
docker compose logs --tail 100 bioagents

Manage Services

# Stop all services
docker compose down

# Stop but keep volumes
docker compose stop

# Restart service
docker compose restart bioagents

# Check status
docker compose ps

Scale Workers

# Scale to 3 worker instances
docker compose up -d --scale worker=3

# Scale back down
docker compose up -d --scale worker=1

Workers automatically share the Redis queue. No additional configuration needed for horizontal scaling.

Access Containers

# Open shell in API server
docker compose exec bioagents sh

# Open shell in worker
docker compose exec worker sh

# Run Redis CLI
docker compose exec redis redis-cli

Environment Variables

LLM Configuration

# Required: At least one LLM provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...

# LLM model selection
REPLY_LLM_PROVIDER=openai
REPLY_LLM_MODEL=gpt-5
HYP_LLM_PROVIDER=google
HYP_LLM_MODEL=gemini-2.5-pro
PLANNING_LLM_PROVIDER=anthropic
PLANNING_LLM_MODEL=claude-sonnet-4-5

Database

# Supabase configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_KEY=eyJ...  # Optional, for admin ops

# For migrations
SUPABASE_FULL_URL=postgresql://postgres:[email protected]:5432/postgres

Job Queue

# Enable queue mode
USE_JOB_QUEUE=true

# Redis connection (auto-configured in docker-compose)
REDIS_URL=redis://redis:6379

# Worker concurrency
CHAT_QUEUE_CONCURRENCY=5
DEEP_RESEARCH_QUEUE_CONCURRENCY=3

Vector Search

# Embedding configuration
EMBEDDING_PROVIDER=openai
TEXT_EMBEDDING_MODEL=text-embedding-3-large

# RAG settings
CHUNK_SIZE=2000
CHUNK_OVERLAP=200
VECTOR_SEARCH_LIMIT=20
RERRANK_FINAL_LIMIT=5
USE_RERANKING=true
SIMILARITY_THRESHOLD=0.45

Worker-Only Deployment

For multi-server deployments, deploy workers separately using docker-compose.worker.yml:

services:
  worker:
    build: .
    command: ["bun", "run", "src/worker.ts"]
    environment:
      - USE_JOB_QUEUE=true
      - REDIS_URL=${REDIS_URL}  # External Redis (e.g., Upstash)
      - SUPABASE_URL=${SUPABASE_URL}
      - SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - NODE_ENV=production
    env_file:
      - .env
    restart: unless-stopped
    stop_grace_period: 8h  # Allow long-running jobs to complete
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

Worker containers use stop_grace_period: 8h to allow deep research jobs (which can run for hours) to complete gracefully during shutdown.

Troubleshooting

Container Won’t Start

Check logs:

docker compose logs bioagents

Common issues:

Missing environment variables → Check .env file
Port already in use → Change PORT in .env
Database connection failed → Verify Supabase credentials

Redis Connection Errors

Verify Redis is running:

docker compose ps redis
docker compose exec redis redis-cli ping  # Should return PONG

Check connection from API:

docker compose exec bioagents sh
$ env | grep REDIS

Worker Not Processing Jobs

Check worker logs:

docker compose logs -f worker

Verify queue connection:

# Check waiting jobs
docker compose exec redis redis-cli LLEN bull:chat:waiting
docker compose exec redis redis-cli LLEN bull:deep-research:waiting

High Memory Usage

Check container stats:

docker stats bioagents worker

Reduce concurrency:

# In .env
CHAT_QUEUE_CONCURRENCY=2
DEEP_RESEARCH_QUEUE_CONCURRENCY=1

Limit container memory:

deploy:
  resources:
    limits:
      memory: 1G

Build Failures

Clear build cache:

docker compose build --no-cache

Check disk space:

df -h
docker system df

Prune unused images:

docker system prune -a

Production Checklist

Next Steps

Job Queue

Configure BullMQ for reliable background processing

Horizontal Scaling

Scale workers across multiple servers

Deployment Overview

Job Queue Architecture

⌘I

Auto-generate your docs

Quick Start
Prerequisites
Clone and Configure
Dockerfile
Docker Compose Configurations
Production (API + Worker + Redis)
Key Features
Common Commands
Start Services
View Logs
Manage Services
Scale Workers
Access Containers
Environment Variables
LLM Configuration
Database
Job Queue
Vector Search
Worker-Only Deployment
Troubleshooting
Container Won’t Start
Redis Connection Errors
Worker Not Processing Jobs
High Memory Usage
Build Failures
Production Checklist
Next Steps

Build docs developers (and LLMs) love

Get started for free Talk to us

Get Started

Core Concepts

Agents

Configuration

Features

Deployment

Advanced

Quick Start

Prerequisites

Clone and Configure

Dockerfile

Docker Compose Configurations

Production (API + Worker + Redis)

Key Features

Common Commands

Start Services

View Logs

Manage Services

Scale Workers

Access Containers

Environment Variables

LLM Configuration

Database

Job Queue

Vector Search

Worker-Only Deployment

Troubleshooting

Container Won’t Start

Redis Connection Errors

Worker Not Processing Jobs

High Memory Usage

Build Failures

Production Checklist

Next Steps

Job Queue

Horizontal Scaling

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agents

Configuration

Features

Deployment

Advanced

​Quick Start

​Prerequisites

​Clone and Configure

​Dockerfile

​Docker Compose Configurations

​Production (API + Worker + Redis)

​Key Features

​Common Commands

​Start Services

​View Logs

​Manage Services

​Scale Workers

​Access Containers

​Environment Variables

​LLM Configuration

​Database

​Job Queue

​Vector Search

​Worker-Only Deployment

​Troubleshooting

​Container Won’t Start

​Redis Connection Errors

​Worker Not Processing Jobs

​High Memory Usage

​Build Failures

​Production Checklist

​Next Steps

Job Queue

Horizontal Scaling

Build docs developers (and LLMs) love

Quick Start

Prerequisites

Clone and Configure

Dockerfile

Docker Compose Configurations

Production (API + Worker + Redis)

Key Features

Common Commands

Start Services

View Logs

Manage Services

Scale Workers

Access Containers

Environment Variables

LLM Configuration

Database

Job Queue

Vector Search

Worker-Only Deployment

Troubleshooting

Container Won’t Start

Redis Connection Errors

Worker Not Processing Jobs

High Memory Usage

Build Failures

Production Checklist

Next Steps