env.example

# Docker Swarm MCP Server Configuration
# Copy this file to .env and configure for your environment
# DO NOT commit .env to version control!

# ==============================================================================
# REQUIRED: Authentication
# ==============================================================================

# Bearer token for MCP client authentication
# Generate with: openssl rand -hex 32
# Tokens are accepted via Authorization header (Bearer <token>) or X-Access-Token header
# Query parameter authentication is not supported for security reasons
MCP_ACCESS_TOKEN=your-secure-token-here-min-32-characters

# ==============================================================================
# OPTIONAL: Multi-Token Authorization
# ==============================================================================

# JSON mapping of tokens to scopes (alternative to single MCP_ACCESS_TOKEN)
# Example: {"token1": ["read-only"], "token2": ["admin"], "token3": ["container-ops"]}
# TOKEN_SCOPES='{"abc123": ["container-ops", "system-ops"], "xyz789": ["admin"]}'

# ==============================================================================
# Docker Connection
# ==============================================================================

# Docker daemon socket (unix, tcp, or ssh)
DOCKER_HOST=unix:///var/run/docker.sock
# DOCKER_HOST=tcp://remote-host:2376
# DOCKER_HOST=ssh://user@remote-host

# TLS configuration (for tcp:// connections)
DOCKER_TLS_VERIFY=0
DOCKER_CERT_PATH=
# DOCKER_CERT_PATH=/path/to/certs  # Directory containing ca.pem, cert.pem, key.pem

# ==============================================================================
# MCP Protocol Configuration
# ==============================================================================

# Transport mode (http or sse)
MCP_TRANSPORT=http

# MCP protocol version
MCP_PROTOCOL_VERSION=2024-11-05

# Tool execution timeouts (seconds)
MCP_TOOL_TIMEOUT=30
MCP_TIMEOUT_READ_OPS=15    # list, get, info operations
MCP_TIMEOUT_WRITE_OPS=30   # create, start, stop operations
MCP_TIMEOUT_DELETE_OPS=45  # remove, delete operations

# Schema validation
ENFORCE_OUTPUT_SCHEMA=false  # Enforce response schema validation
STRICT_CONTEXT_LIMIT=false   # Enforce strict context size limits

# ==============================================================================
# Intent Classification
# ==============================================================================

# Enable automatic task-type detection from queries
INTENT_CLASSIFICATION_ENABLED=true

# Fallback to all tools if no intent detected
INTENT_FALLBACK_TO_ALL=true

# Minimum confidence threshold for intent classification (0.0 - 1.0)
INTENT_MIN_CONFIDENCE=0.0

# Priority: "intent" (use detected intent) or "explicit" (prefer explicit task_type param)
INTENT_PRECEDENCE=intent

# Expose legacy REST API under /api/* (default: false to favor MCP JSON-RPC)
ENABLE_REST_API=false

# Security: Expose MCP route endpoints in /healthz response (default: false for security)
# Only enable this in development/debugging environments
EXPOSE_ENDPOINTS_IN_HEALTHZ=false

# ==============================================================================
# Logging & CORS
# ==============================================================================

# Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# CORS allowed origins (comma-separated)
# Development: Use wildcard or localhost
ALLOWED_ORIGINS=*

# Production: Use specific domain(s)
# ALLOWED_ORIGINS=https://your-domain.com,https://app.your-domain.com

# ==============================================================================
# OPTIONAL: Tailscale Integration
# ==============================================================================
# Tailscale enables secure networking between Docker Swarm nodes and clients
# When enabled, the server will connect to your Tailscale network for secure access

# Master toggle for Tailscale integration (default: false for backward compatibility)
# Set to 'true' to enable Tailscale networking
TAILSCALE_ENABLED=false

# Tailscale authentication key (REQUIRED when Tailscale is enabled)
# SECURITY WARNING: This is a sensitive value, consider using TAILSCALE_AUTH_KEY_FILE instead
# Generate from your Tailscale admin console: https://login.tailscale.com/admin/authkeys
# Example: tskey-auth-abcdef123456...
# TAILSCALE_AUTH_KEY=

# Alternative to TAILSCALE_AUTH_KEY: Path to file containing the auth key
# Recommended for production deployments to avoid exposing auth key in environment
# Example: /run/secrets/tailscale_auth_key
# TAILSCALE_AUTH_KEY_FILE=

# Optional: Custom hostname for this node in Tailscale network
# If not set, defaults to the container hostname or a generated name
# Must follow Tailscale hostname rules (lowercase, numbers, hyphens only)
# Example: docker-swarm-mcp-server-01
# TAILSCALE_HOSTNAME=

# Optional: Tags for this node in Tailscale network (comma-separated)
# Used for ACL policies and node organization
# Format: tag:example,tag:production (must start with 'tag:')
# Example: tag:docker-swarm,tag:production-server
# TAILSCALE_TAGS=

# Optional: Additional Tailscale command-line arguments
# For advanced configuration and Tailscale features
# Example: --accept-routes --advertise-routes=192.168.100.0/24
# TAILSCALE_EXTRA_ARGS=

# State directory for Tailscale configuration and keys (persistent storage)
# Must be a persistent volume in production to maintain node identity
# Default: /var/lib/tailscale
TAILSCALE_STATE_DIR=/var/lib/tailscale

# Timeout for Tailscale operations in seconds
# Controls how long to wait for Tailscale to start and authenticate
# Default: 30 seconds
TAILSCALE_TIMEOUT=30

# ==============================================================================
# Production Security Checklist
# ==============================================================================
# Before deploying to production:
# ✓ Generate strong MCP_ACCESS_TOKEN (openssl rand -hex 32)
# ✓ Set specific ALLOWED_ORIGINS (not *)
# ✓ Deploy behind TLS reverse proxy or VPN
# ✓ Set LOG_LEVEL=INFO (not DEBUG)
# ✓ Enable DOCKER_TLS_VERIFY=1 for remote connections
# ✓ Configure token rotation schedule
# ✓ Set up monitoring and alerting
# ✓ Review SECURITY.md for complete checklist
# ✓ For Tailscale: Use TAILSCALE_AUTH_KEY_FILE instead of TAILSCALE_AUTH_KEY
# ✓ For Tailscale: Ensure TAILSCALE_STATE_DIR is on persistent storage
# ✓ For Tailscale: Configure appropriate ACL policies in Tailscale admin console