Python SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI
Python agentagentopsagents-sdkaianthropicautogencost-estimationcrewaievalsevaluation-metricsgroqlangchainllmmistralollamaopenaiopenai-agents
---
title: "Docker Guide"
description: "Complete guide for running AgentOps with Docker and Docker Compose"
---
# Docker Guide
This guide covers how to run AgentOps backend services using Docker and Docker Compose. This is the recommended approach for both development and production deployments.
## Overview
The AgentOps Docker setup includes:
- **API Server** - FastAPI backend service
- **Dashboard** - Next.js frontend application
- **OpenTelemetry Collector** - Observability and trace collection
- **External Services** - Supabase, ClickHouse (configured separately)
## Docker Compose Configuration
The main `compose.yaml` file in the `/app` directory defines the service architecture:
```yaml
services:
api:
build:
context: ./api
dockerfile: Dockerfile
ports:
- '8000:8000'
environment:
# Database connections
SUPABASE_URL: ${NEXT_PUBLIC_SUPABASE_URL}
SUPABASE_KEY: ${SUPABASE_SERVICE_ROLE_KEY}
CLICKHOUSE_HOST: ${CLICKHOUSE_HOST}
# ... other environment variables
network_mode: 'host'
volumes:
- ./api:/app/api
dashboard:
profiles: ['dashboard']
build:
context: ./dashboard
dockerfile: Dockerfile
ports:
- '3000:3000'
environment:
# Frontend configuration
NEXT_PUBLIC_SUPABASE_URL: ${NEXT_PUBLIC_SUPABASE_URL}
NEXT_PUBLIC_SUPABASE_ANON_KEY: ${NEXT_PUBLIC_SUPABASE_ANON_KEY}
# ... other environment variables
network_mode: 'host'
depends_on:
- api
volumes:
- ./dashboard:/app/
```
## Quick Start with Docker
### 1. Prerequisites
- Docker Engine 20.10+
- Docker Compose 2.0+
- Git
### 2. Clone and Setup
```bash
git clone https://github.com/AgentOps-AI/AgentOps.Next.git
cd AgentOps.Next/app
# Copy environment files
cp .env.example .env
cp api/.env.example api/.env
cp dashboard/.env.example dashboard/.env.local
```
### 3. Configure Environment Variables
Update your `.env` files with your external service credentials:
```env
# .env (root)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
CLICKHOUSE_HOST=your-clickhouse-host
CLICKHOUSE_PASSWORD=your-password
# ... other variables
```
### 4. Start Services
```bash
# Start all services
docker-compose up -d
# Or start with dashboard profile
docker-compose --profile dashboard up -d
# View logs
docker-compose logs -f
```
### 5. Verify Services
- **API Health**: http://localhost:8000/health
- **API Docs**: http://localhost:8000/redoc
- **Dashboard**: http://localhost:3000
## Docker Commands Reference
### Basic Operations
```bash
# Start all services in detached mode
docker-compose up -d
# Start services with dashboard
docker-compose --profile dashboard up -d
# Stop all services
docker-compose down
# Stop and remove volumes
docker-compose down -v
# View service status
docker-compose ps
# View logs for all services
docker-compose logs -f
# View logs for specific service
docker-compose logs -f api
docker-compose logs -f dashboard
```
### Development Commands
```bash
# Rebuild services after code changes
docker-compose build
# Rebuild specific service
docker-compose build api
docker-compose build dashboard
# Force recreate containers
docker-compose up -d --force-recreate
# Scale services (if needed)
docker-compose up -d --scale api=2
```
### Debugging Commands
```bash
# Execute commands in running containers
docker-compose exec api bash
docker-compose exec dashboard sh
# View container resource usage
docker stats
# Inspect service configuration
docker-compose config
# View service networks
docker network ls
docker network inspect app_default
```
## Using Just Commands
The project includes a `justfile` with convenient Docker commands:
```bash
# Start all services
just up
# Stop all services
just down
# View logs
just logs
# Clean up Docker resources
just clean
# Build and run API
just api-build
just api-run
```
## Service-Specific Configuration
### API Service
The API service runs a FastAPI application with the following configuration:
**Dockerfile highlights:**
```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "run.py"]
```
**Key environment variables:**
- `SUPABASE_URL`, `SUPABASE_KEY` - Database connection
- `CLICKHOUSE_HOST`, `CLICKHOUSE_PASSWORD` - Analytics database
- `LOGGING_LEVEL` - Log verbosity (DEBUG, INFO, WARNING, ERROR)
- `SENTRY_DSN` - Error tracking
### Dashboard Service
The Dashboard service runs a Next.js application:
**Dockerfile highlights:**
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]
```
**Key environment variables:**
- `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY` - Frontend auth
- `NEXT_PUBLIC_APP_URL` - API server URL
- `NEXT_PUBLIC_ENVIRONMENT_TYPE` - Environment (development/production)
## OpenTelemetry Collector
The OpenTelemetry Collector is included via a separate compose file:
```yaml
# opentelemetry-collector/compose.yaml
services:
otel-collector:
image: otel/opentelemetry-collector-contrib:latest
command: ["--config=/etc/otel-collector-config.yaml"]
volumes:
- ./config/otel-collector-config.yaml:/etc/otel-collector-config.yaml
ports:
- "4317:4317" # OTLP gRPC receiver
- "4318:4318" # OTLP HTTP receiver
- "8889:8889" # Prometheus metrics
```
## Production Configuration
### Environment Variables for Production
```env
# Security
DEBUG=false
LOGGING_LEVEL=WARNING
JWT_SECRET_KEY=your-secure-jwt-secret
# URLs
PROTOCOL=https
API_DOMAIN=api.yourdomain.com
APP_DOMAIN=yourdomain.com
# Database
CLICKHOUSE_SECURE=true
SUPABASE_URL=https://your-prod-project.supabase.co
# Monitoring
SENTRY_ENVIRONMENT=production
NEXT_PUBLIC_ENVIRONMENT_TYPE=production
```
### Production Docker Compose
For production, you may want to:
1. **Use specific image tags** instead of building locally
2. **Configure resource limits**
3. **Set up health checks**
4. **Use external networks**
Example production overrides (`compose.prod.yaml`):
```yaml
services:
api:
image: agentops/api:v1.0.0
deploy:
resources:
limits:
cpus: '1.0'
memory: 1G
reservations:
cpus: '0.5'
memory: 512M
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
restart: unless-stopped
dashboard:
image: agentops/dashboard:v1.0.0
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
restart: unless-stopped
```
Run with production config:
```bash
docker-compose -f compose.yaml -f compose.prod.yaml up -d
```
## Troubleshooting
### Common Issues
**Services won't start:**
```bash
# Check logs for errors
docker-compose logs api
docker-compose logs dashboard
# Verify environment variables
docker-compose config
```
**Port conflicts:**
```bash
# Check what's using ports
lsof -i :3000
lsof -i :8000
# Use different ports
docker-compose up -d -p 3001:3000 -p 8001:8000
```
**Database connection issues:**
- Verify external service credentials in `.env` files
- Check network connectivity from containers
- Ensure services are accessible from Docker network
**Build failures:**
```bash
# Clean build cache
docker system prune -f
docker-compose build --no-cache
# Check Dockerfile syntax
docker-compose config
```
### Performance Optimization
**Resource monitoring:**
```bash
# Monitor container resources
docker stats
# View container processes
docker-compose exec api top
```
**Volume optimization:**
```bash
# Use named volumes for better performance
volumes:
- api_data:/app/data
- dashboard_cache:/app/.next
```
**Network optimization:**
```bash
# Create custom network for better isolation
networks:
agentops:
driver: bridge
```
## Maintenance
### Regular Maintenance Tasks
```bash
# Update images
docker-compose pull
docker-compose up -d
# Clean up unused resources
docker system prune -f
# Backup volumes
docker run --rm -v app_api_data:/data -v $(pwd):/backup alpine tar czf /backup/api_data.tar.gz -C /data .
# View disk usage
docker system df
```
### Monitoring
```bash
# Service health checks
curl http://localhost:8000/health
curl http://localhost:3000/api/health
# Container logs
docker-compose logs --tail=100 -f api
# Resource usage
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
```
## Next Steps
- Set up [monitoring and observability](/v2/self-hosting/monitoring)
- Configure [production deployment](/v2/self-hosting/deployment)
- Set up [backup and recovery](/v2/self-hosting/backup)
- Configure [SSL/TLS certificates](/v2/self-hosting/ssl)