Skip to main content

​
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

# Check container logs
docker-compose logs weavemcp-agent

# Check container status
docker-compose ps

# Restart services
docker-compose restart

# 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

# 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