Skip to main content
Complete guide to deploying your Bindu agent using Docker Compose, Makefile commands, and various deployment options.

​
Prerequisites

Before deploying your agent, ensure you have:
  • Docker and Docker Compose installed
  • Python 3.12+ (for local development)
  • uv package manager installed
  • Your .env file configured with required API keys

​
Environment Setup

​
1. Configure Environment Variables

Copy the example environment file and add your API keys: 
cp .env.example .env
Edit .env and add your credentials: 
# OpenRouter API Configuration
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Get your API key from: https://openrouter.ai/keys
Never commit your .env file to version control. It’s already included in .gitignore.

​
Docker Compose Deployment

Your agent comes with a complete Docker Compose setup that includes:
  • Main Agent Service - Your Bindu agent
  • Jaeger - Distributed tracing and monitoring
  • Phoenix - LLM observability and debugging

​
Docker Compose Configuration

The docker-compose.yml file defines three services: 
services:
  my_bindu_agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: my_bindu_agent
    ports:
      - "3773:3773"
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - OTEL_EXPORTER_OTLP_ENDPOINT=http://phoenix:4317
    env_file:
      - .env
    volumes:
      - ./my_bindu_agent:/app/my_bindu_agent
      - ./agent_config.json:/app/agent_config.json
    restart: unless-stopped
    networks:
      - my_bindu_agent-network
    depends_on:
      - jaeger
      - phoenix

  jaeger:
    image: jaegertracing/all-in-one:latest
    container_name: my_bindu_agent-jaeger
    ports:
      - "16686:16686"  # Jaeger UI
      - "4318:4318"    # OTLP HTTP receiver
      - "4317:4317"    # OTLP gRPC receiver
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    networks:
      - my_bindu_agent-network
    restart: unless-stopped

  phoenix:
    image: arizephoenix/phoenix:latest
    container_name: my_bindu_agent-phoenix
    ports:
      - "6006:6006"  # Phoenix UI and OTLP HTTP collector
      - "4319:4317"  # OTLP gRPC collector
    environment:
      - PHOENIX_WORKING_DIR=/mnt/data
    volumes:
      - phoenix_data:/mnt/data
    networks:
      - my_bindu_agent-network
    restart: unless-stopped

networks:
  my_bindu_agent-network:
    driver: bridge

volumes:
  phoenix_data:
    driver: local

​
Docker Compose Commands

1

Build and Start Services

Build the Docker images and start all services:
docker-compose up --build
Or run in detached mode (background):
docker-compose up -d --build
2

View Logs

View logs from all services:
docker-compose logs -f
View logs from a specific service:
docker-compose logs -f my_bindu_agent
docker-compose logs -f jaeger
docker-compose logs -f phoenix
3

Stop Services

Stop all running services:
docker-compose down
Stop and remove volumes (clears all data):
docker-compose down -v
4

Restart Services

Restart all services:
docker-compose restart
Restart a specific service:
docker-compose restart my_bindu_agent

​
Access Your Services

Once deployed, access your services at:

Agent API

Your Bindu agent endpoint

Jaeger UI

Distributed tracing dashboard

Phoenix UI

LLM observability dashboard

​
Makefile Commands

Your agent includes a Makefile with common development tasks. Use make help to see all available commands.

​
Development Commands

Install the virtual environment and pre-commit hooks:
make install
This command:
  • Creates a virtual environment using uv
  • Installs all dependencies
  • Sets up pre-commit hooks for code quality
Run all code quality checks:
make check
This command runs:
  • Lock file consistency check
  • Pre-commit hooks (linting, formatting)
  • Static type checking with ty
  • Dependency analysis with deptry
Run tests with coverage:
make test
This command:
  • Runs pytest with coverage reporting
  • Generates XML coverage report
  • Uses configuration from pyproject.toml
Build wheel distribution file:
make build
This command:
  • Cleans previous build artifacts
  • Creates a new wheel file in dist/
  • Uses uv as the installer
Build and serve documentation:
make docs
This starts a local documentation server. Access it at http://localhost:8000To test documentation build without serving:
make docs-test
Clean build artifacts:
make clean-build
Removes the dist/ directory and all build artifacts.
Display all available commands:
make help
Shows a formatted list of all Makefile targets with descriptions.

​
Dockerfile Overview

The Dockerfile uses a multi-stage approach optimized for Python 3.12 and uv: 
# Install uv
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Change the working directory to the `app` directory
WORKDIR /app

# Copy the lockfile and `pyproject.toml` into the image
COPY uv.lock /app/uv.lock
COPY pyproject.toml /app/pyproject.toml

# Install dependencies
RUN uv sync --frozen --no-install-project

# Copy the project into the image
COPY . /app

# Sync the project
RUN uv sync --frozen

CMD ["uv", "run", "python", "-m", "my_bindu_agent.main"]

​
Key Features

  • Slim Base Image - Uses python:3.12-slim for minimal size
  • UV Package Manager - Fast dependency resolution and installation
  • Frozen Dependencies - Ensures reproducible builds with --frozen flag
  • Layer Caching - Dependencies installed before code copy for faster rebuilds

​
Deployment Workflows

​
Local Development

1

Install Dependencies

make install
2

Run Quality Checks

make check
3

Run Tests

make test
4

Start Agent Locally

uv run python -m my_bindu_agent.main

​
Docker Development

1

Configure Environment

cp .env.example .env
# Edit .env with your API keys
2

Build and Run

docker-compose up --build
3

Monitor Logs

docker-compose logs -f my_bindu_agent
4

Test Agent

Access your agent at http://localhost:3773

​
Production Deployment

1

Build Production Image

docker build -t my-bindu-agent:latest .
2

Tag for Registry

docker tag my-bindu-agent:latest your-registry/my-bindu-agent:latest
3

Push to Registry

docker push your-registry/my-bindu-agent:latest
4

Deploy to Production

Use your preferred orchestration platform (Kubernetes, ECS, etc.)

​
Monitoring and Observability

​
Jaeger Tracing

Access Jaeger UI at http://localhost:16686 to:
  • View distributed traces across your agent
  • Analyze request latency and performance
  • Debug issues with detailed span information
  • Monitor service dependencies

​
Phoenix LLM Observability

Access Phoenix UI at http://localhost:6006 to:
  • Track LLM calls and token usage
  • Analyze prompt and response quality
  • Monitor model performance metrics
  • Debug LLM-specific issues
Phoenix uses the OpenInference standard, which is compatible with many observability providers.

​
Troubleshooting

​
Common Issues

If you see port conflict errors:
# Check what's using the port
lsof -i :3773

# Kill the process or change the port in docker-compose.yml
Ensure your .env file exists and is in the project root:
# Verify .env file exists
ls -la .env

# Check environment variables are loaded
docker-compose config
Clear Docker cache and rebuild:
docker-compose down -v
docker system prune -a
docker-compose up --build
Check agent logs for errors:
docker-compose logs -f my_bindu_agent
Verify the agent is healthy:
docker-compose ps
curl http://localhost:3773/health

​
Next Steps

Configure Agent

Customize your agent’s behavior and capabilities

Learn Observability

Deep dive into monitoring and debugging

Join Community

Connect with other agent developers

Get Help

Find support and resources