> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weavemcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Compose

> Deploy WeaveMCP agents with Docker Compose

# 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

```bash theme={null}
mkdir weavemcp-agent
cd weavemcp-agent
```

### 2. Create Docker Compose File

Create `docker-compose.yml`:

```yaml theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
mkdir config logs
```

Create `config/mcp-servers.json`:

```json theme={null}
{
  "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

```bash theme={null}
# Start in detached mode
docker-compose up -d

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

# Check status
docker-compose ps
```

### Verify Deployment

```bash theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
# 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`:

```bash theme={null}
#!/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

<AccordionGroup>
  <Accordion title="Container won't start">
    ```bash theme={null}
    # Check container logs
    docker-compose logs weavemcp-agent

    # Check container status
    docker-compose ps

    # Restart services
    docker-compose restart
    ```
  </Accordion>

  <Accordion title="Agent can't connect to virtual server">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="MCP servers not working">
    ```bash theme={null}
    # 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"
    ```
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable debug mode for detailed logging:

```yaml theme={null}
environment:
  - WEAVEMCP_LOG_LEVEL=debug
  - NODE_ENV=development
```

### Clean Restart

To completely reset the deployment:

```bash theme={null}
# 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:

```yaml theme={null}
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

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Kubernetes Deployment" icon="dharmachakra" href="/setup-an-agent/kubernetes">
    Scale to production with Kubernetes
  </Card>

  <Card title="AWS EC2 Deployment" icon="aws" href="/setup-an-agent/aws-ec2">
    Deploy on Amazon Web Services
  </Card>

  <Card title="Monitoring Guide" icon="chart-line" href="/monitoring">
    Set up comprehensive monitoring
  </Card>

  <Card title="Custom MCP Servers" icon="code" href="/custom-mcp-servers">
    Build your own MCP server integrations
  </Card>
</CardGroup>