Skip to content

container.md

Latest commit

 

History

History
174 lines (121 loc) · 3.95 KB

container.md

File metadata and controls

174 lines (121 loc) · 3.95 KB

📦 Container Deployment

You can run MCP Gateway as a fully self-contained container. This is the recommended method for production or platform-agnostic deployments. You can use any container engine (ex: Docker or Podman).

Quick Start (Pre-built Container Image)

If you just want to run the gateway using the official OCI container image from GitHub Container Registry:

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-test-key \
  -e JWT_AUDIENCE=mcpgateway-api \
  -e JWT_ISSUER=mcpgateway \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  -e PLATFORM_ADMIN_PASSWORD=changeme \
  -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
  -e DATABASE_URL=sqlite:///./mcp.db \
  --network=host \
  ghcr.io/ibm/mcp-context-forge:0.9.0

docker logs mcpgateway

You can now access the UI at http://localhost:4444/admin

Multi-architecture containers

Note: the container build process creates container images for 'amd64', 'arm64' and 's390x' architectures. The version ghcr.io/ibm/mcp-context-forge:VERSION not points to a manifest so that if all commands will pull the correct image for the architecture being used (whether that be locally or on Kubernetes or OpenShift).

If the specific image is needed for one architecture on a different architecture use the appropriate arguments for your given container execution tool:

With docker run:

docker run [... all your options...] --platform linux/arm64 ghcr.io/ibm/mcp-context-forge:VERSION

With podman run:

podman run [... all your options...] --platform linux/arm64 ghcr.io/ibm/mcp-context-forge:VERSION

Or

podman run [... all your options...] --arch arm64 ghcr.io/ibm/mcp-context-forge:VERSION

🐳 Build the Container

Using Podman (recommended)

make podman

Using Docker (manual alternative)

docker build -t mcpgateway:latest -f Containerfile .

The base image uses python:3.11-slim with Gunicorn and Uvicorn workers.

🔒 Airgapped Deployments

For environments without internet access, you can build a container with all UI assets bundled locally.

Build Airgapped Container

Use Containerfile.lite which automatically downloads CDN assets during build:

docker build -f Containerfile.lite -t mcpgateway:airgapped .

This downloads and bundles:

  • Tailwind CSS (~404KB)
  • HTMX (~52KB)
  • CodeMirror (~216KB)
  • Alpine.js (~48KB)
  • Chart.js (~208KB)

Total: ~932KB of UI assets

Run in Airgapped Mode

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e MCPGATEWAY_UI_AIRGAPPED=true \
  -e MCPGATEWAY_UI_ENABLED=true \
  -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-test-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  mcpgateway:airgapped

!!! success "Fully Offline UI" With MCPGATEWAY_UI_AIRGAPPED=true, the Admin UI works completely offline with zero external dependencies. All CSS and JavaScript are served from local files bundled in the container.

🏃 Run the Container

With HTTP (no TLS)

make podman-run

This starts the app at http://localhost:4444.

With Self-Signed TLS (HTTPS)

make podman-run-ssl

Runs the gateway using certs from ./certs/, available at:

https://localhost:4444

⚙ Runtime Configuration

All environment variables can be passed via:

  • docker run -e KEY=value
  • A mounted .env file (--env-file .env)

🧪 Test the Running Container

curl http://localhost:4444/health
curl http://localhost:4444/tools

Use curl -k if running with self-signed TLS

🧼 Stop & Clean Up

podman stop mcpgateway
podman rm mcpgateway

Or with Docker:

docker stop mcpgateway
docker rm mcpgateway
⚡