🧩 Docker Compose¶

Running MCP Gateway with Compose spins up a full stack (Gateway, Postgres, Redis, optional MCP servers) behind a single YAML file. The Makefile detects Podman or Docker automatically, and you can override it with COMPOSE_CMD=. Health-checks (service_healthy) gate the Gateway until the database is ready, preventing race conditions. If dependencies become temporarily unavailable, the Gateway uses exponential backoff with jitter for connection retries—see Startup Resilience for details.

🚀 Automated Setup Script¶

For fresh Linux systems, the contextforge-setup.sh script automates the entire setup process including Docker installation, user configuration, and starting the Compose stack.

Supported Distributions¶

• Ubuntu, Debian (and derivatives like Linux Mint, Pop!_OS)
• Rocky Linux, RHEL, CentOS, AlmaLinux, Fedora

Quick Start¶

# 1. Create a dedicated user (as root)
useradd -m contextforge && passwd contextforge
usermod -aG wheel contextforge   # RHEL-family
usermod -aG sudo contextforge    # Debian-family

# 2. Switch to the new user
su - contextforge

# 3. Clone the repository and run the setup script
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge
./scripts/contextforge-setup.sh

The script will install Docker, configure the user, clone the repository (if not already present), and start the Compose stack.

Script Options¶

Environment Variables for Automated Docker Login¶

Examples¶

# Non-interactive install without starting services
./scripts/contextforge-setup.sh -y --skip-start

# Automated install with Docker Hub credentials
DOCKER_USERNAME=myuser DOCKER_PASSWORD=mypass ./scripts/contextforge-setup.sh -y

# Install to custom directory
./scripts/contextforge-setup.sh ~/my-contextforge

Configure the compose command to use¶

For example, install and use Docker Compose v2:

sudo apt install docker-buildx docker-compose-v2
export COMPOSE_CMD="docker compose"

🐳/🦭 Build the images¶

docker pull ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-2

🐳/🦭 Build the images (when doing local development)¶

Using Make (preferred)¶

Remember to tag the image or configure the correct image in docker-compose.yml

Manual equivalents¶

# Podman (dev image)
podman build -t mcpgateway-dev:latest -f Containerfile .

# Podman (prod image, AMD64, squash layers)
podman build --platform=linux/amd64 --squash \
  -t mcpgateway:latest -f Containerfile.lite .

# Docker (dev image)
docker build -t mcpgateway-dev:latest -f Containerfile .

# Docker (prod image)
docker build -t mcpgateway:latest -f Containerfile.lite .

Apple Silicon caveat Containerfile.lite derives from ubi9-micro. Running it via QEMU emulation on M-series Macs often fails with a glibc x86-64-v2 error. Use the regular image or build a native linux/arm64 variant on Mac.

🏃 Start the Compose stack¶

With Make¶

make compose-up                   # auto-detects engine
COMPOSE_CMD="docker compose" make compose-up   # force Docker
COMPOSE_CMD="podman compose" make compose-up   # force Podman

Without Make¶

🌐 Access and verify¶

• Gateway URL: http://localhost:8080 (Nginx reverse proxy; gateway port 4444 is not published in Compose.)

curl http://localhost:8080/health    # {"status":"healthy"}

• Logs: make compose-logs or raw docker compose logs -f gateway.

🗄 Selecting a database¶

Uncomment one service block in docker-compose.yml and align DATABASE_URL:

Named volumes (pgdata, mariadbdata, mysqldata, mongodata) isolate persistent data.

🔀 PgBouncer Connection Pooling¶

PgBouncer is a lightweight connection pooler for PostgreSQL that reduces connection overhead and improves throughput under high concurrency. PgBouncer is enabled by default in the Docker Compose configuration.

Default Architecture¶

Gateway (2 replicas × 16 workers) → PgBouncer → PostgreSQL (max_connections=500)

Benefits of PgBouncer (enabled by default):

• Connection multiplexing: Many app connections share fewer database connections
• Reduced PostgreSQL overhead: Lower max_connections reduces memory per connection
• Connection reuse: PgBouncer maintains persistent connections to PostgreSQL
• Graceful handling of connection storms: Queues requests instead of rejecting

Disabling PgBouncer (Direct PostgreSQL)¶

If you need to bypass PgBouncer for debugging or specific workloads:

1. Update gateway DATABASE_URL to connect directly to PostgreSQL:

# In gateway environment section, change:
- DATABASE_URL=postgresql+psycopg://postgres:mysecretpassword@pgbouncer:6432/mcp
# To:
- DATABASE_URL=postgresql+psycopg://postgres:mysecretpassword@postgres:5432/mcp

1. Increase gateway pool settings:

# Change from:
- DB_POOL_SIZE=10
- DB_MAX_OVERFLOW=20
# To:
- DB_POOL_SIZE=50
- DB_MAX_OVERFLOW=100

1. Increase PostgreSQL max_connections:

# In postgres command section, change:
- "max_connections=500"
# To:
- "max_connections=4000"

1. Update gateway depends_on to wait for PostgreSQL directly:

depends_on:
  postgres:
    condition: service_healthy
  redis:
    condition: service_started

Pool Modes¶

PgBouncer supports three pool modes:

Configuration Reference¶

Monitoring PgBouncer¶

Connect to PgBouncer's admin console:

# Connect to PgBouncer admin
docker compose exec pgbouncer psql -p 6432 -U postgres pgbouncer

# View pool statistics
SHOW STATS;

# View current pools
SHOW POOLS;

# View active clients
SHOW CLIENTS;

# View server connections
SHOW SERVERS;

Troubleshooting¶

Connection timeouts:

• Increase RESERVE_POOL_SIZE for burst handling
• Check if MAX_DB_CONNECTIONS is sufficient

Slow queries with PgBouncer:

• Verify pool mode is appropriate for your workload
• Check for long-running transactions holding connections

Authentication failures:

• Ensure AUTH_TYPE matches PostgreSQL's pg_hba.conf
• Verify password is correct in DATABASE_URL

🔐 TLS/HTTPS Support¶

Enable HTTPS with zero configuration using the TLS profile:

make compose-tls

This automatically:

• Generates self-signed certificates (if ./certs/ is empty)
• Starts nginx with TLS on port 8443
• Keeps HTTP available on port 8080

TLS Commands¶

Using Custom Certificates¶

mkdir -p certs
cp /path/to/cert.pem certs/cert.pem
cp /path/to/key.pem certs/key.pem
make compose-tls

Access Points¶

• HTTP: http://localhost:8080
• HTTPS: https://localhost:8443
• Admin UI: https://localhost:8443/admin

For advanced TLS configuration (end-to-end encryption, custom ciphers, etc.), see TLS Configuration Guide.

🔄 Lifecycle cheatsheet¶

<engine> = docker, podman, or podman-compose as shown earlier.

🔍 Troubleshooting port publishing on WSL2 (rootless Podman)¶

# Verify the port is listening (dual-stack)
ss -tlnp | grep 8080        # modern tool
netstat -anp | grep 8080    # legacy fallback

A line like LISTEN rootlessport is normal - the IPv6 wildcard socket (::) also accepts IPv4 when net.ipv6.bindv6only=0 (the default on Linux).

WSL2 quirk

WSL's NAT maps only the IPv6 side, so http://127.0.0.1:8080 fails from Windows. Tell Podman you are inside WSL and restart your containers:

# inside the WSL distro
echo "wsl" | sudo tee /etc/containers/podman-machine

ss should now show an explicit 0.0.0.0:8080 listener, making the service reachable from Windows and the LAN.

📚 References¶

• Docker Compose CLI (up, logs, down) - official docs
• Podman's integrated compose wrapper - man page
• podman-compose rootless implementation - GitHub project
• Health-check gating with depends_on: condition: service_healthy
• UBI9 runtime on Apple Silicon limitations (x86_64-v2 glibc)
• General Containerfile build guidance (Fedora/Red Hat)