-
Notifications
You must be signed in to change notification settings - Fork 614
[TESTING][DEPLOYMENT]: Docker, Docker Compose, Kubernetes/Helm, and Bare Metal Installation #2475
Copy link
Copy link
Open
Labels
SHOULDP2: Important but not vital; high-value items that are not crucial for the immediate releaseP2: Important but not vital; high-value items that are not crucial for the immediate releasechoreLinting, formatting, dependency hygiene, or project maintenance choresLinting, formatting, dependency hygiene, or project maintenance choreshelmHelm chartHelm chartmanual-testingManual testing / test planning issuesManual testing / test planning issuesreadyValidated, ready-to-work-on itemsValidated, ready-to-work-on itemstestingTesting (unit, e2e, manual, automated, etc)Testing (unit, e2e, manual, automated, etc)
Milestone
Description
[TESTING][DEPLOYMENT]: Docker, Docker Compose, Kubernetes/Helm, and Bare Metal Installation
Goal
Produce a comprehensive manual test plan for validating all documented deployment methods work correctly including Docker, Docker Compose, Kubernetes/Helm, and bare metal Python installations.
Why Now?
Deployment testing ensures accessibility for all users:
- First Experience: Installation is the first user touchpoint
- Documentation Accuracy: Quickstart guides must actually work
- Environment Diversity: Users have varied infrastructure
- Support Reduction: Working deployments reduce support burden
- Onboarding Speed: Smooth installs accelerate adoption
User Stories
US-1: Developer - Quick Local Setup
As a developer
I want to run the gateway locally with Docker Compose
So that I can evaluate it quickly
Acceptance Criteria:
Feature: Docker Compose Deployment
Scenario: Full stack with docker-compose
Given Docker and Docker Compose installed
When I run docker-compose up
Then gateway should start with PostgreSQL and Redis
And I should be able to register an MCP server
And Admin UI should be accessibleUS-2: Platform Engineer - Kubernetes Deploy
As a platform engineer
I want to deploy via Helm chart
So that I can manage it like other Kubernetes workloads
Acceptance Criteria:
Feature: Helm Deployment
Scenario: Helm install with defaults
Given a Kubernetes cluster
When I run helm install with default values
Then the deployment should succeed
And all pods should be healthy
And ingress should route traffic correctlyArchitecture
DEPLOYMENT OPTIONS
+------------------------------------------------------------------------+
| |
| Docker Single Docker Compose Kubernetes |
| ------------- -------------- ---------- |
| |
| +-----------+ +-----------------+ +---------------+ |
| | Gateway | | Gateway | | Gateway | |
| | SQLite | | PostgreSQL | | Deployment | |
| +-----------+ | Redis | +---------------+ |
| +-----------------+ | |
| v |
| Bare Metal +---------------+ |
| ---------- | Service + | |
| | Ingress | |
| +-----------+ +---------------+ |
| | Python | | |
| | venv | v |
| | Gateway | +---------------+ |
| +-----------+ | PostgreSQL | |
| | Redis | |
| +---------------+ |
| |
+------------------------------------------------------------------------+
Test Environment Setup
# Common requirements
export GATEWAY_VERSION="1.0.0"
# Docker setup
docker --version # Verify Docker installed
docker-compose --version # or: docker compose version
# Kubernetes setup (for Helm tests)
kubectl version --client
helm version
# Python setup (for bare metal)
python3 --version # Should be 3.11+
uv --version # For venv managementManual Test Cases
| Case | Method | Configuration | Expected Result |
|---|---|---|---|
| DEP-01 | Docker single | SQLite, no Redis | Basic functionality |
| DEP-02 | Docker Compose | PostgreSQL + Redis | Full stack works |
| DEP-03 | Helm minimal | Default values | Deploys successfully |
| DEP-04 | Helm full | All features enabled | HA configuration |
| DEP-05 | Bare metal pip | pip install | Works on clean system |
| DEP-06 | Bare metal uv | uv venv + install | Works with uv |
| DEP-07 | Offline install | Air-gapped | Pre-downloaded images work |
DEP-01: Docker Single Container
Steps:
# Pull and run single container
docker run -d --name mcpgateway \
-p 8000:8000 \
-e JWT_SECRET_KEY=test-secret-key \
-e AUTH_REQUIRED=true \
ghcr.io/anthropics/mcpgateway:$GATEWAY_VERSION
# Wait for startup
sleep 10
# Verify health
curl -s http://localhost:8000/health | jq '.status'Validation:
# Generate token
docker exec mcpgateway python -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --secret test-secret-key
# Test API
TOKEN=<token-from-above>
curl -s "http://localhost:8000/gateways" \
-H "Authorization: Bearer $TOKEN" | jq '.items'
# Check Admin UI
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/ui/Expected Result:
- Container starts without errors
- Health endpoint returns
{"status": "healthy"} - API responds with authentication
- Admin UI accessible at /ui/
Cleanup:
docker stop mcpgateway && docker rm mcpgatewayDEP-02: Docker Compose Full Stack
docker-compose.yml:
version: '3.8'
services:
gateway:
image: ghcr.io/anthropics/mcpgateway:${GATEWAY_VERSION}
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://gateway:gateway@postgres/gateway
- REDIS_URL=redis://redis:6379
- JWT_SECRET_KEY=compose-secret-key
depends_on:
- postgres
- redis
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 10s
timeout: 5s
retries: 5
postgres:
image: postgres:15
environment:
- POSTGRES_USER=gateway
- POSTGRES_PASSWORD=gateway
- POSTGRES_DB=gateway
volumes:
- pgdata:/var/lib/postgresql/data
redis:
image: redis:7-alpine
volumes:
- redisdata:/data
volumes:
pgdata:
redisdata:Steps:
# Start full stack
docker-compose up -d
# Wait for healthy
docker-compose ps
sleep 30
# Verify all services
docker-compose exec gateway curl -s http://localhost:8000/health | jq .Validation:
# Test database persistence
TOKEN=$(docker-compose exec gateway python -m mcpgateway.utils.create_jwt_token \
--username admin@example.com --secret compose-secret-key)
# Create data
curl -s -X POST "http://localhost:8000/gateways" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "compose-test", "url": "http://example.com"}'
# Restart and verify persistence
docker-compose restart gateway
sleep 15
curl -s "http://localhost:8000/gateways" -H "Authorization: Bearer $TOKEN" | jq '.items[].name'Expected Result:
- All three services start and become healthy
- Gateway connects to PostgreSQL and Redis
- Data persists across restarts
Cleanup:
docker-compose down -vDEP-03: Helm Minimal Installation
Steps:
# Add Helm repo (if applicable)
helm repo add mcpgateway https://charts.mcpgateway.io
helm repo update
# Install with defaults
helm install mcpgateway ./charts/mcpgateway \
--namespace mcpgateway \
--create-namespace \
--set config.jwtSecretKey=helm-secret-key
# Wait for deployment
kubectl rollout status deployment/mcpgateway -n mcpgateway --timeout=120sValidation:
# Check pod status
kubectl get pods -n mcpgateway
# Check service
kubectl get svc -n mcpgateway
# Port forward and test
kubectl port-forward svc/mcpgateway 8000:80 -n mcpgateway &
sleep 5
curl -s http://localhost:8000/health | jq '.status'Expected Result:
- Helm install completes without errors
- Pod reaches Running state
- Health check passes
- Default configuration works
Cleanup:
helm uninstall mcpgateway -n mcpgateway
kubectl delete namespace mcpgatewayDEP-04: Helm Full HA Configuration
values-ha.yaml:
replicaCount: 3
config:
jwtSecretKey: ha-secret-key
databaseUrl: postgresql://user:pass@postgres-ha/gateway
redisUrl: redis://redis-ha:6379
ingress:
enabled: true
className: nginx
hosts:
- host: gateway.example.com
paths:
- path: /
pathType: Prefix
resources:
requests:
cpu: 500m
memory: 512Mi
limits:
cpu: 2000m
memory: 2Gi
autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 10
targetCPUUtilizationPercentage: 70Steps:
helm install mcpgateway ./charts/mcpgateway \
--namespace mcpgateway \
--create-namespace \
-f values-ha.yaml
# Verify HA
kubectl get pods -n mcpgateway
# Should show 3 podsExpected Result:
- All 3 replicas start successfully
- Load balancing works across replicas
- HPA configured correctly
- Ingress routes traffic
DEP-05: Bare Metal Installation (pip)
Steps:
# Create clean virtual environment
python3 -m venv gateway-env
source gateway-env/bin/activate
# Install from PyPI (or local wheel)
pip install mcpgateway
# Configure
export JWT_SECRET_KEY=baremetal-secret
export DATABASE_URL=sqlite:///./gateway.db
export HOST=0.0.0.0
export PORT=8000
# Run
mcpgateway serve &
sleep 10
# Verify
curl -s http://localhost:8000/health | jq .Expected Result:
- Installation completes without errors
- Server starts successfully
- SQLite database created
- API responds correctly
Cleanup:
deactivate
rm -rf gateway-env gateway.dbDEP-06: Bare Metal Installation (uv)
Steps:
# Create environment with uv
uv venv gateway-uv-env
source gateway-uv-env/bin/activate
# Install
uv pip install mcpgateway
# Same configuration and verification as DEP-05Expected Result:
- uv installation works correctly
- Same functionality as pip install
Test Matrix
| Method | Database | Redis | UI | Federation | Pass Criteria |
|---|---|---|---|---|---|
| Docker single | SQLite | No | Yes | No | Basic works |
| Docker Compose | PostgreSQL | Yes | Yes | Yes | Full stack |
| Helm minimal | SQLite | No | Yes | No | Default works |
| Helm HA | PostgreSQL | Yes | Yes | Yes | 3 replicas |
| Bare metal pip | SQLite | No | Yes | No | Clean install |
| Bare metal uv | SQLite | No | Yes | No | uv works |
Success Criteria
- All quickstart guides tested and working
- Default configurations work without modification
- Environment variables documented and validated
- Health checks pass on all deployment methods
- Data persists correctly (PostgreSQL, volumes)
- Admin UI accessible on all deployments
- Troubleshooting guide covers common issues
Related Files
docker-compose.yml- Compose configurationDockerfile- Container image buildcharts/mcpgateway/- Helm chartpyproject.toml- Python package definitionMakefile- Build targets (make serve, etc.)
Related Issues
- [TESTING][UPGRADE]: Version Upgrades, Database Migrations, and Rollback Procedures #2474 - Upgrade testing
- [TESTING][CONFIGURATION]: Environment Variables, Validation, and Default Values #2478 - Configuration validation
- [TESTING][RESILIENCE]: Kubernetes Resilience Manual Test Plan (Pod Deletion, Node Failure, Rolling Updates) #2468 - Kubernetes resilience
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
SHOULDP2: Important but not vital; high-value items that are not crucial for the immediate releaseP2: Important but not vital; high-value items that are not crucial for the immediate releasechoreLinting, formatting, dependency hygiene, or project maintenance choresLinting, formatting, dependency hygiene, or project maintenance choreshelmHelm chartHelm chartmanual-testingManual testing / test planning issuesManual testing / test planning issuesreadyValidated, ready-to-work-on itemsValidated, ready-to-work-on itemstestingTesting (unit, e2e, manual, automated, etc)Testing (unit, e2e, manual, automated, etc)