Deploy with Docker Compose

Use Docker Compose to deploy WeaveMCP agents for local development and testing environments.

Prerequisites

Docker and Docker Compose installed
WeaveMCP account with virtual server created
Agent token generated from the web console

Quick Setup

1. Create Directory Structure

mkdir weavemcp-agent
cd weavemcp-agent

2. Create Docker Compose File

Create docker-compose.yml:

version: '3.8'

services:
  weavemcp-agent:
    image: weavemcp/agent:latest
    container_name: weavemcp-agent
    restart: unless-stopped
    environment:
      - WEAVEMCP_AGENT_TOKEN=${WEAVEMCP_AGENT_TOKEN}
      - WEAVEMCP_SERVER_URL=${WEAVEMCP_SERVER_URL}
      - WEAVEMCP_LOG_LEVEL=info
    ports:
      - "8080:8080"  # Health check port
      - "9090:9090"  # Metrics port
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
    networks:
      - weavemcp-network

networks:
  weavemcp-network:
    driver: bridge

3. Create Environment File

Create .env file:

# Required configuration
WEAVEMCP_AGENT_TOKEN=your-agent-token-here
WEAVEMCP_SERVER_URL=https://your-virtual-server.weavemcp.dev

# Optional configuration
WEAVEMCP_LOG_LEVEL=info
WEAVEMCP_HEALTH_CHECK_PORT=8080
WEAVEMCP_METRICS_PORT=9090

4. Create Configuration Directory

mkdir config logs

Create config/mcp-servers.json:

{
  "mcpServers": {
    "filesystem-server": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/data"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "git-server": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-git", "/repos"],
      "env": {
        "GIT_AUTHOR_NAME": "WeaveMCP Agent",
        "GIT_AUTHOR_EMAIL": "agent@weavemcp.com"
      }
    }
  }
}

Deployment

Start Services

# Start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f weavemcp-agent

# Check status
docker-compose ps

Verify Deployment

# Check agent health
curl http://localhost:8080/health

# Check detailed status
curl http://localhost:8080/status

# View metrics
curl http://localhost:9090/metrics

Advanced Configuration

With MCP Server Volumes

To provide MCP servers access to local files:

version: '3.8'

services:
  weavemcp-agent:
    image: weavemcp/agent:latest
    container_name: weavemcp-agent
    restart: unless-stopped
    environment:
      - WEAVEMCP_AGENT_TOKEN=${WEAVEMCP_AGENT_TOKEN}
      - WEAVEMCP_SERVER_URL=${WEAVEMCP_SERVER_URL}
      - WEAVEMCP_LOG_LEVEL=info
    ports:
      - "8080:8080"
      - "9090:9090"
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
      - ./data:/data:ro          # Filesystem server data
      - ./repos:/repos           # Git repositories
      - /var/run/docker.sock:/var/run/docker.sock:ro  # Docker access
    networks:
      - weavemcp-network

networks:
  weavemcp-network:
    driver: bridge

With External Dependencies

If your MCP servers need databases or other services:

version: '3.8'

services:
  weavemcp-agent:
    image: weavemcp/agent:latest
    container_name: weavemcp-agent
    restart: unless-stopped
    environment:
      - WEAVEMCP_AGENT_TOKEN=${WEAVEMCP_AGENT_TOKEN}
      - WEAVEMCP_SERVER_URL=${WEAVEMCP_SERVER_URL}
      - WEAVEMCP_LOG_LEVEL=info
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/mcpdb
    ports:
      - "8080:8080"
      - "9090:9090"
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
    depends_on:
      - postgres
      - redis
    networks:
      - weavemcp-network

  postgres:
    image: postgres:15
    container_name: weavemcp-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_DB=mcpdb
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - weavemcp-network

  redis:
    image: redis:7-alpine
    container_name: weavemcp-redis
    restart: unless-stopped
    volumes:
      - redis_data:/data
    networks:
      - weavemcp-network

volumes:
  postgres_data:
  redis_data:

networks:
  weavemcp-network:
    driver: bridge

Development Mode

For local development with hot reloading:

version: '3.8'

services:
  weavemcp-agent:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: weavemcp-agent-dev
    restart: unless-stopped
    environment:
      - WEAVEMCP_AGENT_TOKEN=${WEAVEMCP_AGENT_TOKEN}
      - WEAVEMCP_SERVER_URL=${WEAVEMCP_SERVER_URL}
      - WEAVEMCP_LOG_LEVEL=debug
      - NODE_ENV=development
    ports:
      - "8080:8080"
      - "9090:9090"
      - "9229:9229"  # Node.js debugger
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
      - ./src:/app/src  # Source code for hot reloading
    networks:
      - weavemcp-network

networks:
  weavemcp-network:
    driver: bridge

Monitoring and Logs

Log Management

View and manage logs:

# View recent logs
docker-compose logs --tail=100 weavemcp-agent

# Follow logs in real-time
docker-compose logs -f weavemcp-agent

# View logs from specific time
docker-compose logs --since="2024-01-15T10:00:00" weavemcp-agent

# Export logs
docker-compose logs --no-color weavemcp-agent > agent-logs.txt

Health Monitoring

Create a simple monitoring script monitor.sh:

#!/bin/bash

# Health check function
check_health() {
    response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/health)
    if [ "$response" = "200" ]; then
        echo "$(date): Agent is healthy"
        return 0
    else
        echo "$(date): Agent health check failed (HTTP $response)"
        return 1
    fi
}

# Main monitoring loop
while true; do
    if ! check_health; then
        echo "$(date): Restarting agent..."
        docker-compose restart weavemcp-agent
        sleep 30
    fi
    sleep 60
done

Troubleshooting

Common Issues

Container won't start

# Check container logs
docker-compose logs weavemcp-agent

# Check container status
docker-compose ps

# Restart services
docker-compose restart

Agent can't connect to virtual server

# Verify environment variables
docker-compose config

# Check network connectivity
docker-compose exec weavemcp-agent curl -I https://console.weavemcp.com

# Verify token is valid
echo $WEAVEMCP_AGENT_TOKEN

MCP servers not working

# Check MCP server configuration
docker-compose exec weavemcp-agent cat /app/config/mcp-servers.json

# Test MCP server directly
docker-compose exec weavemcp-agent npx @modelcontextprotocol/server-filesystem --help

# Check agent logs for MCP errors
docker-compose logs weavemcp-agent | grep -i "mcp\|error"

Debug Mode

Enable debug mode for detailed logging:

environment:
  - WEAVEMCP_LOG_LEVEL=debug
  - NODE_ENV=development

Clean Restart

To completely reset the deployment:

# Stop and remove containers
docker-compose down

# Remove volumes (WARNING: This deletes data)
docker-compose down -v

# Remove images
docker-compose down --rmi all

# Start fresh
docker-compose up -d

Production Considerations

Resource Limits

Set resource limits for production:

services:
  weavemcp-agent:
    # ... other config
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

Security

Use Docker secrets for sensitive data
Run containers as non-root users
Keep images updated
Use specific image tags instead of latest
Enable Docker Content Trust

Backup Strategy

# Backup configuration and data
tar -czf weavemcp-backup-$(date +%Y%m%d).tar.gz \
  docker-compose.yml .env config/ data/ logs/

# Restore from backup
tar -xzf weavemcp-backup-20240115.tar.gz
docker-compose up -d

Next Steps

Kubernetes Deployment

Scale to production with Kubernetes

AWS EC2 Deployment

Deploy on Amazon Web Services

Monitoring Guide

Set up comprehensive monitoring

Custom MCP Servers

Build your own MCP server integrations

Getting started

Agent Deployment

Development

Customization

Writing content

AI tools

Docker Compose

Deploy with Docker Compose

Prerequisites

Quick Setup

1. Create Directory Structure

2. Create Docker Compose File

3. Create Environment File

4. Create Configuration Directory

Deployment

Start Services

Verify Deployment

Advanced Configuration

With MCP Server Volumes

With External Dependencies

Development Mode

Monitoring and Logs

Log Management

Health Monitoring

Troubleshooting

Common Issues

Debug Mode

Clean Restart

Production Considerations

Resource Limits

Security

Backup Strategy

Next Steps

Kubernetes Deployment

AWS EC2 Deployment

Monitoring Guide

Custom MCP Servers

Getting started

Agent Deployment

Development

Customization

Writing content

AI tools

​Deploy with Docker Compose

​Prerequisites

​Quick Setup

​1. Create Directory Structure

​2. Create Docker Compose File

​3. Create Environment File

​4. Create Configuration Directory

​Deployment

​Start Services

​Verify Deployment

​Advanced Configuration

​With MCP Server Volumes

​With External Dependencies

​Development Mode

​Monitoring and Logs

​Log Management

​Health Monitoring

​Troubleshooting

​Common Issues

​Debug Mode

​Clean Restart

​Production Considerations

​Resource Limits

​Security

​Backup Strategy

​Next Steps

Kubernetes Deployment

AWS EC2 Deployment

Monitoring Guide

Custom MCP Servers

Deploy with Docker Compose

Prerequisites

Quick Setup

1. Create Directory Structure

2. Create Docker Compose File

3. Create Environment File

4. Create Configuration Directory

Deployment

Start Services

Verify Deployment

Advanced Configuration

With MCP Server Volumes

With External Dependencies

Development Mode

Monitoring and Logs

Log Management

Health Monitoring

Troubleshooting

Common Issues

Debug Mode

Clean Restart

Production Considerations

Resource Limits

Security

Backup Strategy

Next Steps