mcvsphere/README_DOCKER.md

# mcvsphere - Docker Guide

This guide provides instructions for running the mcvsphere using Docker and Docker Compose.

## Quick Start

### Prerequisites

- Docker 20.10+
- Docker Compose 2.0+
- Access to a VMware vCenter Server or ESXi host

### 1. Setup

```bash
# Clone the repository
git clone <repository-url>
cd mcvsphere

# Create necessary directories and configuration
make setup

# Create environment variables file (optional)
make env-example
cp .env.example .env
```

### 2. Configuration

You have two options for configuration:

#### Option A: Configuration File (Recommended)

Edit `config/config.yaml`:

```yaml
vcenter_host: "your-vcenter-ip"
vcenter_user: "administrator@vsphere.local"
vcenter_password: "your-password"
datacenter: "your-datacenter"
cluster: "your-cluster"
datastore: "your-datastore"
network: "VM Network"
insecure: true
api_key: "your-api-key"
log_level: "INFO"
```

#### Option B: Environment Variables

Edit `.env` file:

```bash
VCENTER_HOST=your-vcenter-ip
VCENTER_USER=administrator@vsphere.local
VCENTER_PASSWORD=your-password
VCENTER_DATACENTER=your-datacenter
VCENTER_CLUSTER=your-cluster
VCENTER_DATASTORE=your-datastore
VCENTER_NETWORK=VM Network
VCENTER_INSECURE=true
MCP_API_KEY=your-api-key
MCP_LOG_LEVEL=INFO
```

### 3. Run the Server

```bash
# Build and run
make dev

# Or run in background
make run

# Check status
make status

# View logs
make logs
```

## Available Commands

Use `make help` to see all available commands:

```bash
make help
```

### Build Commands

- `make build` - Build Docker image
- `make build-no-cache` - Build without cache

### Run Commands

- `make run` - Run in background
- `make run-logs` - Run with logs
- `make stop` - Stop containers
- `make restart` - Restart containers

### Development Commands

- `make dev` - Development mode (build + run with logs)
- `make logs` - Show logs
- `make shell` - Open bash shell in container
- `make status` - Show container status
- `make health` - Check container health

### Maintenance Commands

- `make clean` - Remove containers and volumes
- `make clean-all` - Remove everything
- `make update` - Rebuild and restart

## Docker Architecture

### Multi-stage Build

The Dockerfile uses a multi-stage build process:

1. **Builder Stage**: Installs build dependencies and Python packages
2. **Production Stage**: Creates a minimal runtime image

### Security Features

- Runs as non-root user (`mcpuser`)
- Minimal base image (python:3.11-slim)
- Only necessary runtime dependencies
- Configurable resource limits

### Directory Structure

```
/app/
├── server.py              # Main application
├── config.yaml.sample     # Configuration template
├── docker-entrypoint.sh   # Startup script
├── config/                # Configuration directory (mounted)
│   └── config.yaml        # Runtime configuration
└── logs/                  # Log directory (mounted)
    └── vmware_mcp.log     # Application logs
```

## Configuration Options

### Volume Mounts

- `./config.yaml:/app/config/config.yaml:ro` - Configuration file (read-only)
- `./logs:/app/logs` - Log directory

### Environment Variables

All configuration options can be set via environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `VCENTER_HOST` | vCenter/ESXi hostname | Required |
| `VCENTER_USER` | Username | Required |
| `VCENTER_PASSWORD` | Password | Required |
| `VCENTER_DATACENTER` | Datacenter name | Auto-detect |
| `VCENTER_CLUSTER` | Cluster name | Auto-detect |
| `VCENTER_DATASTORE` | Datastore name | Auto-detect |
| `VCENTER_NETWORK` | Network name | VM Network |
| `VCENTER_INSECURE` | Skip SSL verification | true |
| `MCP_API_KEY` | API authentication key | None |
| `MCP_LOG_LEVEL` | Log level | INFO |

### Resource Limits

Default resource limits in docker-compose.yml:

- **Memory**: 512MB limit, 256MB reserved
- **CPU**: 0.5 cores limit, 0.25 cores reserved

## Health Checks

The container includes automatic health checks:

- **Interval**: 30 seconds
- **Timeout**: 10 seconds
- **Retries**: 3
- **Start Period**: 40 seconds

Check health manually:

```bash
make health
```

## Networking

The server exposes:

- **Port 8080**: HTTP API endpoint
- **Path `/sse`**: Server-Sent Events endpoint
- **Path `/sse/messages`**: JSON-RPC messages endpoint

## Troubleshooting

### Check Logs

```bash
make logs
```

### Check Container Status

```bash
make status
```

### Open Shell in Container

```bash
make shell
```

### Common Issues

1. **Configuration not found**: Ensure `config/config.yaml` exists or environment variables are set
2. **Permission denied**: Check that the `logs` directory is writable
3. **Connection failed**: Verify vCenter/ESXi connectivity and credentials
4. **Health check failed**: Check if the server is responding on port 8080

### Debug Mode

Run with debug logging:

```bash
# Set in .env file
MCP_LOG_LEVEL=DEBUG

# Or in config.yaml
log_level: "DEBUG"
```

## OAuth Multi-User Mode

For shared infrastructure or production deployments, mcvsphere supports OAuth 2.1 with any OIDC provider. This enables:

- **Browser-based authentication** via Authentik, Keycloak, Auth0, Okta, etc.
- **Group-based RBAC** with 5 permission levels
- **Audit logging** with user identity

### Quick Start (Existing OIDC Provider)

If you already have an OIDC provider:

```bash
# 1. Copy and configure environment
cp .env.oauth.example .env
# Edit .env with your OIDC provider details

# 2. Start mcvsphere with OAuth
docker compose -f docker-compose.oauth-standalone.yml up -d

# 3. Add to Claude Code
claude mcp add -t http vsphere https://mcp.example.com/mcp
```

### Quick Start (New Authentik Deployment)

To deploy mcvsphere with a complete Authentik identity provider:

```bash
# 1. Generate secrets and configure
./scripts/setup-oauth.sh

# 2. Start full stack (mcvsphere + Authentik + PostgreSQL + Redis)
docker compose -f docker-compose.oauth.yml up -d

# 3. Configure Authentik at https://auth.yourdomain.com
#    - Create OAuth2 provider
#    - Create vsphere-* groups
#    - Assign users to groups
```

### RBAC Permission Groups

Create these groups in your OIDC provider:

| Group | Access Level |
|-------|--------------|
| `vsphere-super-admins` | Full control (all 94 tools) |
| `vsphere-host-admins` | Host operations + VM management |
| `vsphere-admins` | VM lifecycle management |
| `vsphere-operators` | Power ops + snapshots |
| `vsphere-readers` | Read-only |

Users without any `vsphere-*` group are denied access (default-deny security).

### Required Environment Variables

```bash
# Transport (must be streamable-http for OAuth)
MCP_TRANSPORT=streamable-http

# OIDC Provider
OAUTH_ENABLED=true
OAUTH_ISSUER_URL=https://auth.example.com/application/o/mcvsphere/
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_BASE_URL=https://mcp.example.com
```

See [OAUTH-ARCHITECTURE.md](OAUTH-ARCHITECTURE.md) for detailed setup and troubleshooting.

---

## Production Deployment

### Security Recommendations

1. Use a dedicated service account for vCenter access
2. Enable OAuth authentication (not API keys)
3. Use valid SSL certificates (set `VCENTER_INSECURE=false`)
4. Limit container resources
5. Use Docker secrets for sensitive data
6. Deploy behind a reverse proxy with HTTPS (Caddy recommended)

### High Availability

For production deployments, consider:

- Running multiple container instances
- Using a load balancer
- Implementing persistent storage for logs
- Setting up monitoring and alerting

## Examples

### Basic Usage

```bash
# Start the server
make run

# Check if it's working
curl http://localhost:8080/sse
```

### API Authentication

```bash
# With API key
curl -H "Authorization: Bearer your-api-key" http://localhost:8080/sse
```

### Development

```bash
# Development workflow
make build
make dev

# Make changes to code
# Rebuild and restart
make update
```