Merge pull request #38 from IBM/add-minikube-docs

Add support for minikube in Makefile and update documentation

Author: crivetimihai

Makefile

@@ -1282,3 +1282,102 @@ ibmcloud-ce-status:
 ibmcloud-ce-rm:
 	@echo "🗑️  Deleting Code Engine app: $(IBMCLOUD_CODE_ENGINE_APP)…"
 	@ibmcloud ce application delete --name $(IBMCLOUD_CODE_ENGINE_APP) -f
+
+
+# =============================================================================
+# 🧪 MINIKUBE LOCAL CLUSTER
+# =============================================================================
+# help: 🧪 MINIKUBE LOCAL CLUSTER
+# help: minikube-install      - Install Minikube (macOS, Linux, or Windows via choco)
+# help: minikube-start        - Start local Minikube cluster with Ingress + DNS + metrics-server
+# help: minikube-stop         - Stop the Minikube cluster
+# help: minikube-delete       - Delete the Minikube cluster
+# help: minikube-image-load   - Build and load ghcr.io/ibm/mcp-context-forge:latest into Minikube
+# help: minikube-k8s-apply    - Apply Kubernetes manifests from k8s/
+# help: minikube-status       - Show status of Minikube and ingress pods
+
+.PHONY: minikube-install minikube-start minikube-stop minikube-delete \
+        minikube-image-load minikube-k8s-apply minikube-status
+
+minikube-install:
+	@echo "💻 Detecting OS and installing Minikube + kubectl…"
+	@if [ "$$(uname)" = "Darwin" ]; then \
+	  echo "🍎 Installing via Homebrew…"; \
+	  brew install minikube kubernetes-cli; \
+	elif [ "$$(uname)" = "Linux" ]; then \
+	  echo "🐧 Installing via direct download…"; \
+	  curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 && \
+	  sudo install minikube-linux-amd64 /usr/local/bin/minikube && \
+	  rm minikube-linux-amd64; \
+	  echo "🔧 Installing kubectl…"; \
+	  curl -LO "https://dl.k8s.io/release/$$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
+	  chmod +x kubectl && sudo mv kubectl /usr/local/bin/; \
+	elif command -v powershell.exe >/dev/null; then \
+	  echo "🪟 Installing via Chocolatey…"; \
+	  powershell.exe -Command "choco install -y minikube kubernetes-cli"; \
+	else \
+	  echo "❌ Unsupported OS. Please install manually."; \
+	  exit 1; \
+	fi
+
+minikube-start:
+	@echo "🚀 Starting Minikube with profile 'mcpgw'..."
+	minikube start \
+	  --driver=docker \
+	  --cpus=4 --memory=6g \
+	  --profile=mcpgw
+	@echo "🔌 (Re)enabling required addons…"
+	minikube addons enable ingress -p mcpgw
+	minikube addons enable ingress-dns -p mcpgw
+	minikube addons enable metrics-server -p mcpgw
+
+minikube-stop:
+	@echo "🛑 Stopping Minikube cluster..."
+	minikube stop -p mcpgw
+
+minikube-delete:
+	@echo "🗑 Deleting Minikube cluster..."
+	minikube delete -p mcpgw
+
+minikube-image-load:
+	@echo "📦 Loading image into Minikube (must be pre-built)..."
+	@if ! docker image inspect ghcr.io/ibm/mcp-context-forge:latest >/dev/null 2>&1; then \
+	  echo "❌ Image ghcr.io/ibm/mcp-context-forge:latest not found. Download or build it first."; \
+	  exit 1; \
+	fi
+	minikube image load ghcr.io/ibm/mcp-context-forge:latest -p mcpgw
+	@echo "🔍 Verifying image presence inside Minikube..."
+	minikube ssh -p mcpgw "sudo crictl images | grep ghcr.io/ibm/mcp-context-forge || echo '❌ Image not found in Minikube runtime'"
+
+minikube-k8s-apply:
+	@echo "🧩 Applying Kubernetes manifests..."
+	kubectl apply -f k8s/postgres-config.yaml || true
+	kubectl apply -f k8s/postgres-pv.yaml || true
+	kubectl apply -f k8s/postgres-pvc.yaml || true
+	kubectl apply -f k8s/postgres-deployment.yaml
+	kubectl apply -f k8s/postgres-service.yaml
+	kubectl apply -f k8s/redis-deployment.yaml
+	kubectl apply -f k8s/redis-service.yaml
+	kubectl apply -f k8s/mcp-context-forge-deployment.yaml
+	kubectl apply -f k8s/mcp-context-forge-service.yaml
+	kubectl apply -f k8s/mcp-context-forge-ingress.yaml
+	minikube status -p mcpgw
+
+minikube-status:
+	@echo "📊 Minikube cluster status:"
+	minikube status -p mcpgw
+
+	@echo "\n📦 Addon status (ingress, ingress-dns, metrics-server):"
+	minikube addons list | grep -E 'ingress|ingress-dns|metrics-server'
+
+	@echo "\n🚦 Ingress controller pods:"
+	kubectl get pods -n ingress-nginx -o wide || true
+
+	@echo "\n🧭 Ingress-DNS pods (coredns):"
+	kubectl get pods -n kube-system -l k8s-app=kube-dns -o wide || true
+
+	@echo "\n🧩 Application services:"
+	kubectl get svc || true
+
+	@echo "\n🌐 Application ingress:"
+	kubectl get ingress || true

README.md

@@ -102,7 +102,7 @@ If you just want to run the gateway using the official image from GitHub Contain
 docker run -d --name mcpgateway \
   -p 4444:4444 \
   -e HOST=0.0.0.0 \
-  -e JWT_SECRET_KEY=my-secret-key \
+  -e JWT_SECRET_KEY=my-test-key \
   -e BASIC_AUTH_USER=admin \
   -e BASIC_AUTH_PASSWORD=changeme \
   -e AUTH_REQUIRED=true \
@@ -112,6 +112,8 @@ docker run -d --name mcpgateway \
 docker logs mcpgateway
 ```
 
+You can now access the UI at [http://localhost:4444/admin](http://localhost:4444/admin)
+
 > 💡 You can also use `--env-file .env` if you have a config file already. See the provided [.env.example](.env.example)
 
 ### Optional: Mount a local volume for persistent SQLite storage
@@ -123,16 +125,19 @@ docker logs mcpgateway
 ### Generate a token for API access
 
 ```bash
-export MCPGATEWAY_BEARER_TOKEN=$(docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)
+export MCPGATEWAY_BEARER_TOKEN=$(docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 100800 --secret my-test-key)
+echo ${MCPGATEWAY_BEARER_TOKEN}
 ```
 
 ### Smoke-test the running container
 
 ```bash
 curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
-     http://localhost:4444/health
+     http://localhost:4444/health | jq
 curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      http://localhost:4444/tools | jq
+curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+     http://localhost:4444/version | jq
 ```
 
 ### Running the mcpgateway-wrapper
@@ -210,19 +215,14 @@ make lint          # optional: run style checks (ruff, mypy, etc.)
 
 ### Containerised (self-signed TLS)
 
-```bash
-make podman            # build production image
-make podman-run-ssl    # run at https://localhost:4444
-```
 
-### Generate an admin JWT
+> You can use docker or podman, ex:
 
 ```bash
-python -m mcpgateway.utils.create_jwt_token \
-       -u admin \
-       -e 10080 | tee token.txt   # 7 days (minutes)
-
-export MCPGATEWAY_BEARER_TOKEN=$(cat token.txt)
+make podman            # build production image
+make podman-run-ssl    # run at https://localhost:4444
+# or listen on port 4444 on your host directly, adds --network=host to podman
+make podman-run-ssl-host
 ```
 
 ### Smoke-test the API
@@ -614,7 +614,7 @@ curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
      http://localhost:4444/protocol/ping
 
-# Completion for prompt/resource arguments
+# Completion for prompt/resource arguments (not implemented)
 curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
@@ -623,7 +623,7 @@ curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
          }' \
      http://localhost:4444/protocol/completion/complete
 
-# Sampling (streaming)
+# Sampling (streaming) (not implemented)
 curl -N -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
@@ -682,6 +682,8 @@ curl -X PUT -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
 # Toggle active status
 curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      http://localhost:4444/tools/1/toggle?activate=false
+curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+     http://localhost:4444/tools/1/toggle?activate=true
 
 # Delete tool
 curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools/1
@@ -692,7 +694,7 @@ curl -X DELETE -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localh
 ### Gateway Management (`/gateways`)
 
 ```bash
-# Register a peer gateway
+# Register an MCP server as a new gateway provider
 curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"name":"peer_gateway","url":"http://peer:4444"}' \
@@ -896,7 +898,7 @@ curl -X POST -H "Content-Type: application/json" \
 ## Testing
 
 ```bash
-make tests           # Run unit tests
+make test            # Run unit tests
 make lint            # Run lint tools
 ```
 

docker-compose.yml

@@ -24,7 +24,7 @@ services:
   # MCP Gateway - the main API server for the MCP stack
   # ──────────────────────────────────────────────────────────────────────
   gateway:
-    image: mcpgateway/mcpgateway
+    image: ghcr.io/ibm/mcp-context-forge:latest
     build:
       context: .
       dockerfile: Containerfile     # Same one the Makefile builds

docs/docs/deployment/compose.md

@@ -1,13 +1,28 @@
 # 🧩 Docker Compose
 
 Running **MCP Gateway** with **Compose** spins up a full stack (Gateway, Postgres, Redis, optional MPC servers) behind a single YAML file.
-The Makefile detects Podman or Docker automatically, and you can override it with `COMPOSE_ENGINE=`.
+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.
 
 ---
 
+## Configure the compose command to use
+
+For example, install and use Docker Compose v2:
+
+```bash
+sudo apt install docker-buildx docker-compose-v2
+export COMPOSE_CMD="docker compose"
+```
+
 ## 🐳/🦭 Build the images
 
+```bash
+docker pull ghcr.io/ibm/mcp-context-forge:latest
+```
+
+## 🐳/🦭 Build the images (when doing local development)
+
 ### Using Make (preferred)
 
 | Target             | Image                   | Dockerfile             | Notes                         |
@@ -17,6 +32,8 @@ Health-checks (`service_healthy`) gate the Gateway until the database is ready,
 | `make docker`      | `mcpgateway:latest`     | **Containerfile**      | Docker Desktop / CI runners   |
 | `make docker-prod` | `mcpgateway:latest`     | **Containerfile.lite** | Same multi-stage "lite" build |
 
+Remember to tag the image or configure the correct image in `docker-compose.yml`
+
 ### Manual equivalents
 
 ```bash

docs/docs/deployment/container.md

@@ -1,6 +1,6 @@
 # 📦 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 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).
 
 ---