Docker 가이드

Docker 가이드 (Docker Guide)

Docker와 Docker Compose로 AgentOps를 실행하는 완전한 가이드를 소개해요. 설정, 커맨드 레퍼런스, 프로덕션 구성, 문제 해결까지 알아볼게요.

출처: 문서

본문

Docker 가이드

이 가이드는 Docker와 Docker Compose를 사용해 AgentOps 백엔드 서비스를 실행하는 방법을 다룹니다. 이는 개발과 프로덕션 배포 모두에 권장되는 방법입니다.

개요 (Overview)

AgentOps Docker 설정은 다음을 포함합니다.

  • API Server - FastAPI 백엔드 서비스
  • Dashboard - Next.js 프론트엔드 애플리케이션
  • OpenTelemetry Collector - 관측성과 트레이스 수집
  • External Services - Supabase, ClickHouse (별도로 설정)

Docker Compose 설정 (Docker Compose Configuration)

/app 디렉토리의 메인 compose.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/

Docker 퀵 스타트 (Quick Start with Docker)

1. 사전 요구사항 (Prerequisites)

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • Git

2. 클론과 설정 (Clone and Setup)

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)

외부 서비스 자격 증명으로 .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)

# 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)

Docker 커맨드 레퍼런스 (Docker Commands Reference)

기본 작업 (Basic Operations)

# 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)

# 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)

# 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

Just 명령어 사용 (Using Just Commands)

프로젝트는 편리한 Docker 명령어가 있는 justfile을 포함합니다.

# 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 서비스 (API Service)

API 서비스는 다음 설정으로 FastAPI 애플리케이션을 실행합니다.

Dockerfile 하이라이트:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "run.py"]

핵심 환경 변수:

  • SUPABASE_URL, SUPABASE_KEY - 데이터베이스 연결
  • CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD - 분석 데이터베이스
  • LOGGING_LEVEL - 로그 상세도 (DEBUG, INFO, WARNING, ERROR)
  • SENTRY_DSN - 오류 추적

대시보드 서비스 (Dashboard Service)

대시보드 서비스는 Next.js 애플리케이션을 실행합니다.

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"]

핵심 환경 변수:

  • NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY - 프론트엔드 인증
  • NEXT_PUBLIC_APP_URL - API 서버 URL
  • NEXT_PUBLIC_ENVIRONMENT_TYPE - 환경 (development/production)

OpenTelemetry Collector

OpenTelemetry Collector는 별도의 compose 파일로 포함됩니다.

# 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)

# 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

프로덕션 Docker Compose

프로덕션에서는 다음을 고려할 수 있습니다.

  1. 로컬 빌드 대신 특정 이미지 태그 사용
  2. 리소스 제한 설정
  3. 헬스 체크 구성
  4. 외부 네트워크 사용

프로덕션 오버라이드 예제 (compose.prod.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

프로덕션 설정으로 실행:

docker-compose -f compose.yaml -f compose.prod.yaml up -d

문제 해결 (Troubleshooting)

일반적인 문제 (Common Issues)

서비스가 시작되지 않음 (Services won't start):

# Check logs for errors
docker-compose logs api
docker-compose logs dashboard

# Verify environment variables
docker-compose config

포트 충돌 (Port conflicts):

# 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):

  • .env 파일의 외부 서비스 자격 증명을 확인하세요
  • 컨테이너에서 네트워크 연결을 확인하세요
  • 서비스가 Docker 네트워크에서 접근 가능한지 확인하세요

빌드 실패 (Build failures):

# Clean build cache
docker system prune -f
docker-compose build --no-cache

# Check Dockerfile syntax
docker-compose config

성능 최적화 (Performance Optimization)

리소스 모니터링:

# Monitor container resources
docker stats

# View container processes
docker-compose exec api top

볼륨 최적화:

# Use named volumes for better performance
volumes:
  - api_data:/app/data
  - dashboard_cache:/app/.next

네트워크 최적화:

# Create custom network for better isolation
networks:
  agentops:
    driver: bridge

유지보수 (Maintenance)

정기 유지보수 작업 (Regular Maintenance Tasks)

# 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)

# 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)

더 알아보기 (Learn more)