Skip to content

[TESTING][DEPLOYMENT]: Docker, Docker Compose, Kubernetes/Helm, and Bare Metal Installation #2475

@crivetimihai

Description

@crivetimihai

[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:

  1. First Experience: Installation is the first user touchpoint
  2. Documentation Accuracy: Quickstart guides must actually work
  3. Environment Diversity: Users have varied infrastructure
  4. Support Reduction: Working deployments reduce support burden
  5. 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 accessible
US-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 correctly

Architecture

                    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 management

Manual 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 mcpgateway
DEP-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 -v
DEP-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=120s

Validation:

# 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 mcpgateway
DEP-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: 70

Steps:

helm install mcpgateway ./charts/mcpgateway \
  --namespace mcpgateway \
  --create-namespace \
  -f values-ha.yaml

# Verify HA
kubectl get pods -n mcpgateway
# Should show 3 pods

Expected 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.db
DEP-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-05

Expected 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 configuration
  • Dockerfile - Container image build
  • charts/mcpgateway/ - Helm chart
  • pyproject.toml - Python package definition
  • Makefile - Build targets (make serve, etc.)

Related Issues

Metadata

Metadata

Assignees

No one assigned

    Labels

    SHOULDP2: Important but not vital; high-value items that are not crucial for the immediate releasechoreLinting, formatting, dependency hygiene, or project maintenance choreshelmHelm chartmanual-testingManual testing / test planning issuesreadyValidated, ready-to-work-on itemstestingTesting (unit, e2e, manual, automated, etc)

    Type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions