Skip to content

DOCKER.md

Latest commit

 

History

History
281 lines (198 loc) · 5.69 KB

DOCKER.md

File metadata and controls

281 lines (198 loc) · 5.69 KB

Docker Deployment Guide

This guide explains how to build and run pytest-agents using Docker containers.

Prerequisites

  • Docker Engine 20.10+ or Docker Desktop
  • Docker Compose 2.0+

Quick Start

Build and Run

# Build the Docker image
docker-compose build

# Run verification
docker-compose up pytest-agents

# Run tests
docker-compose --profile test up pytest-agents-test

# Start development shell
docker-compose --profile dev run pytest-agents-dev

Docker Services

Main Service (pytest-agents)

The default service that runs the pytest-agents verification command.

docker-compose up pytest-agents

Test Service (pytest-agents-test)

Runs the full test suite with coverage reporting.

docker-compose --profile test up pytest-agents-test

Coverage reports are saved to the test-coverage volume.

Development Service (pytest-agents-dev)

Interactive shell for development work.

docker-compose --profile dev run pytest-agents-dev

Building the Image

Standard Build

docker build -t pytest-agents:latest .

Multi-Architecture Build

docker buildx build --platform linux/amd/amd64,linux/arm64 -t pytest-agents:latest .

Running Containers

Run Verification

docker run --rm pytest-agents:latest pytest-agents verify

Run Specific Agent

docker run --rm pytest-agents:latest pytest-agents agent pm list_tasks

Run Tests

docker run --rm pytest-agents:latest uv run pytest -v

Interactive Shell

docker run --rm -it pytest-agents:latest /bin/bash

Environment Variables

Configure pytest-agents using environment variables:

docker run --rm \
  -e PYTEST_AGENTS_AGENT_PM_ENABLED=true \
  -e PYTEST_AGENTS_AGENT_TIMEOUT=60 \
  -e PYTEST_AGENTS_LOG_LEVEL=DEBUG \
  pytest-agents:latest pytest-agents verify

Available variables:

  • PYTEST_AGENTS_PROJECT_ROOT - Project root directory (default: /app)
  • PYTEST_AGENTS_AGENT_PM_ENABLED - Enable PM agent (default: true)
  • PYTEST_AGENTS_AGENT_RESEARCH_ENABLED - Enable Research agent (default: true)
  • PYTEST_AGENTS_AGENT_INDEX_ENABLED - Enable Index agent (default: true)
  • PYTEST_AGENTS_AGENT_TIMEOUT - Agent timeout in seconds (default: 30)
  • PYTEST_AGENTS_AGENT_RETRY_COUNT - Agent retry count (default: 3)
  • PYTEST_AGENTS_LOG_LEVEL - Logging level (default: INFO)
  • PYTEST_AGENTS_ENABLE_AGENT_CACHING - Enable caching (default: true)
  • PYTEST_AGENTS_ENABLE_PARALLEL_AGENTS - Enable parallel execution (default: false)

Volume Mounts

Development Mode

Mount source code for live updates:

docker run --rm -it \
  -v $(pwd)/src:/app/src \
  -v $(pwd)/tests:/app/tests \
  pytest-agents:latest /bin/bash

Agent State Persistence

Persist agent memory and state:

docker run --rm \
  -v pytest-agents-data:/app/.agent-memory \
  pytest-agents:latest pytest-agents verify

Docker Compose Profiles

Default Profile

Runs only the main pytest-agents service:

docker-compose up

Test Profile

Includes the test runner service:

docker-compose --profile test up

Dev Profile

Includes the development shell service:

docker-compose --profile dev up

Multi-Stage Build

The Dockerfile uses multi-stage builds for optimization:

  1. Stage 1 (ts-builder): Builds TypeScript agents
  2. Stage 2 (runtime): Python runtime with Node.js and built agents

This approach:

  • Reduces final image size
  • Separates build and runtime dependencies
  • Improves build caching

Security Considerations

  • Container runs as root by default; consider adding a non-root user for production
  • Mount secrets as read-only volumes, not environment variables
  • Use Docker secrets for sensitive configuration in production
  • Regularly update base images for security patches

Troubleshooting

Build Failures

# Clean build (no cache)
docker build --no-cache -t pytest-agents:latest .

# Check build logs
docker-compose build --progress=plain

Runtime Issues

# View container logs
docker-compose logs pytest-agents

# Check running containers
docker ps -a

# Inspect container
docker inspect pytest-agents

Agent Path Issues

If agents can't be found:

# Verify agent files exist in container
docker run --rm pytest-agents:latest ls -la /app/pm/dist
docker run --rm pytest-agents:latest ls -la /app/research/dist
docker run --rm pytest-agents:latest ls -la /app/index/dist

Production Deployment

Using Docker Compose

# docker-compose.prod.yml
version: '3.8'
services:
  pytest-agents:
    image: pytest-agents:latest
    restart: always
    environment:
      - PYTEST_AGENTS_LOG_LEVEL=WARNING
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

Deploy:

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

Health Checks

Add to Dockerfile:

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD pytest-agents verify || exit 1

CI/CD Integration

GitHub Actions Example

name: Docker Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: docker build -t pytest-agents:${{ github.sha }} .
      - name: Run tests in container
        run: docker run --rm pytest-agents:${{ github.sha }} uv run pytest -v

Additional Resources