Docker Deployment

Agent Studio provides Docker images for easy deployment. This guide covers both local development and production deployment.

Prerequisites

Docker 24.0+
Docker Compose 2.20+
4GB RAM minimum (8GB recommended)

Local Development

Quick Start

Clone the repository:

git clone https://github.com/tap-health/agent-studio.git
cd agent-studio

Copy environment file:

cp .env.example .env

Start all services:

docker-compose -f docker/docker-compose.yml up -d

Check service status:

docker-compose -f docker/docker-compose.yml ps

Services

The development stack includes:

Service	Port	Description
`api`	8000	FastAPI server with hot reload
`worker`	-	LiveKit voice worker
`db`	5432	PostgreSQL 16
`redis`	6379	Redis 7
`livekit`	7880	LiveKit server (dev mode)

Accessing Services

API: http://localhost:8000
API Docs: http://localhost:8000/docs
PostgreSQL: postgresql://postgres:postgres@localhost:5432/agent_studio
Redis: redis://localhost:6379

Development Workflow

The API service mounts your source code and enables hot reload:

volumes:
  - ../src:/app/src:ro

Changes to Python files automatically restart the server.

Viewing Logs

# All services
docker-compose -f docker/docker-compose.yml logs -f

# Specific service
docker-compose -f docker/docker-compose.yml logs -f api

# Last 100 lines
docker-compose -f docker/docker-compose.yml logs --tail=100 api

Stopping Services

# Stop all
docker-compose -f docker/docker-compose.yml down

# Stop and remove volumes (reset data)
docker-compose -f docker/docker-compose.yml down -v

Production Deployment

Building the Image

The production Dockerfile uses multi-stage builds for smaller images:

docker build -t agent-studio:latest -f docker/Dockerfile .

Image features:

Multi-stage build (builder + runtime)
Non-root user
Health checks
Minimal dependencies

Environment Variables

Required environment variables for production:

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname

# Redis
REDIS_URL=redis://host:6379/0

# Security (generate secure values!)
JWT_SECRET=your-secure-jwt-secret-min-32-chars
ENCRYPTION_KEY=your-secure-encryption-key-32chars

# LiveKit
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret

Running the API

docker run -d \
  --name agent-studio-api \
  -p 8000:8000 \
  -e DATABASE_URL=postgresql+asyncpg://... \
  -e REDIS_URL=redis://... \
  -e JWT_SECRET=... \
  -e ENCRYPTION_KEY=... \
  agent-studio:latest

Running the Worker

docker run -d \
  --name agent-studio-worker \
  -e DATABASE_URL=postgresql+asyncpg://... \
  -e REDIS_URL=redis://... \
  -e LIVEKIT_URL=wss://... \
  -e LIVEKIT_API_KEY=... \
  -e LIVEKIT_API_SECRET=... \
  agent-studio:latest \
  python -m agent_studio.worker.entrypoint

Docker Compose for Production

Create a docker-compose.prod.yml:

version: "3.9"

services:
  api:
    image: agent-studio:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - JWT_SECRET=${JWT_SECRET}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - LOG_LEVEL=INFO
    healthcheck:
      test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8000/health/live')"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '1'
          memory: 1G

  worker:
    image: agent-studio:latest
    restart: unless-stopped
    command: ["python", "-m", "agent_studio.worker.entrypoint"]
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - LIVEKIT_URL=${LIVEKIT_URL}
      - LIVEKIT_API_KEY=${LIVEKIT_API_KEY}
      - LIVEKIT_API_SECRET=${LIVEKIT_API_SECRET}
      - API_BASE_URL=http://api:8000
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: '2'
          memory: 2G

Health Checks

The Docker image includes health checks:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import httpx; httpx.get('http://localhost:8000/health/live', timeout=5)"

Health endpoints:

/health/live - Container is running
/health/ready - Ready to accept traffic
/health - Full health with dependencies

Resource Requirements

Minimum (Development)

CPU: 2 cores
RAM: 4GB
Disk: 10GB

Recommended (Production)

CPU: 4+ cores
RAM: 8GB+
Disk: 50GB+ SSD

Per-Service Guidelines

Service	CPU	RAM	Notes
API	0.5-1 core	512MB-1GB	Scale horizontally
Worker	1-2 cores	1-2GB	CPU for audio processing
PostgreSQL	1-2 cores	2-4GB	SSD recommended
Redis	0.5 core	512MB	For session state

Troubleshooting

Container Won't Start

# Check logs
docker logs agent-studio-api

# Check if port is in use
lsof -i :8000

Database Connection Issues

# Test connectivity
docker run --rm -it postgres:16 \
  psql postgresql://user:pass@host:5432/dbname -c "SELECT 1"

Memory Issues

# Check container memory
docker stats agent-studio-api

# Increase limits
docker run --memory=2g ...

Permission Issues

The container runs as non-root user appuser (UID 1000). Ensure mounted volumes have correct permissions:

chown -R 1000:1000 /path/to/mounted/volume

Docker Deployment

On this page