β‘οΈ Minikube¶
- Install Minikube and kubectl (Docker or Podman driver required).
- Start a local cluster with Ingress and DNS addons.
- Load the
ghcr.io/ibm/mcp-context-forge:0.6.0
image into Minikube. - Apply your Kubernetes manifests.
- Access the Gateway at http://gateway.local or
127.0.0.1:80
via NGINX Ingress.
Minikube provides a self-contained environment, enabling you to replicate production features like persistent volumes and TLS on your local machine.
π Prerequisites¶
Requirement | Notes |
---|---|
CPU / RAM | Minimum 2 vCPU + 2 GiB; recommended 4 vCPU / 6 GiB for smoother operation. |
Disk | At least 20 GiB of free space. |
Container driver | Docker 20.10+ or Podman 4.7+; Docker is the simplest choice on macOS and Windows. |
kubectl | Automatically configured by minikube start ; alternatively, use minikube kubectl -- ... if not installed. |
Architecture¶
βββββββββββββββββββββββββββββββ
β NGINX Ingress β
ββββββββββββ¬ββββββββββββ¬βββββββ
β/ β/
ββββββββββββββββΌββββββ ββββββΌββββββββββββ
β MCP Context Forge β β PgAdmin (opt.) β
βββββββββββ¬βββββββββββ ββββββ¬ββββββββββββ
β β
ββββββββββββββΌβββββββ ββββββββββΌβββββββββββββ
β PostgreSQL β β Redis Commander(opt)β
ββββββββββ¬βββββββββββ ββββββββββ¬βββββββββββββ
β β
βββββββΌβββββ βββββββΌβββββ
β PV β β Redis β
ββββββββββββ ββββββββββββ
π Step 1 - Install Minikube and kubectl¶
Make target
This target checks for existing installations of minikube
and kubectl
. If missing, it installs them using:
- Homebrew on macOS
- The official binary on Linux
- Chocolatey on Windows
Manual installation (optional)
### macOS (Homebrew) ### Linux (Generic binary)# Minikube
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
# kubectl (latest stable)
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/
βοΈ Step 2 - Start the cluster¶
Make target
Equivalent manual command
--driver=docker
avoids nested virtualization on macOS and Windows Home.ingress
provides an NGINX LoadBalancer on localhost.ingress-dns
resolves*.local
domains when you add the Minikube IP to your OS DNS list.--cpus
and--memory
can be set tomax
to utilize all available resources.
Check cluster status:
π Step 3 - Load the Gateway image¶
Make target
This target builds the ghcr.io/ibm/mcp-context-forge:0.6.0
image and loads it into Minikube.
Alternative methods¶
- Pre-cache a remote image:
- Load a local tarball:
π Step 4 - Apply Kubernetes manifests¶
Make target
This applies the Kubernetes manifests. Alternative manual step:
# PostgreSQL
kubectl apply -f deployment/k8s/postgres-config.yaml
kubectl apply -f deployment/k8s/postgres-pv.yaml
kubectl apply -f deployment/k8s/postgres-pvc.yaml
kubectl apply -f deployment/k8s/postgres-deployment.yaml
kubectl apply -f deployment/k8s/postgres-service.yaml
# Redis
kubectl apply -f deployment/k8s/redis-deployment.yaml
kubectl apply -f deployment/k8s/redis-service.yaml
# MCP Gateway
kubectl apply -f deployment/k8s/mcp-context-forge-deployment.yaml
kubectl apply -f deployment/k8s/mcp-context-forge-service.yaml
kubectl apply -f deployment/k8s/mcp-context-forge-ingress.yaml
If you've enabled ingress-dns
, set the Ingress host:
to gateway.local
. Otherwise, omit the host:
and access via NodePort.
Note: Minikube automatically configures the kubectl
context upon cluster creation. If not, set it manually:
π§ͺ Step 5 - Verify deployment status¶
Before hitting your endpoint, confirm the application is up and healthy.
π Check pod status¶
Expect output like:
NAME READY STATUS RESTARTS AGE
postgres-5b66bdf445-rp8kl 1/1 Running 0 15s
redis-668976c4f9-2hljd 1/1 Running 0 15s
mcp-context-forge-6d87f8c5d8-nnmgx 1/1 Running 0 10s
π Check logs (optional)¶
This can help diagnose startup errors or missing dependencies (e.g. bad env vars, Postgres connection issues).
π₯ Wait for rollout (optional)¶
If the pod gets stuck in CrashLoopBackOff
, run:
And:
β Confirm Ingress is live¶
Should show something like:
If ADDRESS
is empty, the ingress controller may still be warming up.
You may want to add this to /etc/hosts
. Ex:
π Step 6 - Test access¶
# Via NodePort:
curl $(minikube service mcp-context-forge --url)/health
# Via DNS:
curl http://gateway.local/health
π§Ή Cleaning up¶
Action | Make target | Manual command |
---|---|---|
Pause cluster | make minikube-stop | minikube stop -p mcpgw |
Delete cluster | make minikube-delete | minikube delete -p mcpgw |
Remove cached image | - | minikube cache delete ghcr.io/ibm/mcp-context-forge:0.6.0 |
π Non-Make cheatsheet¶
Task | Command |
---|---|
Start with Podman driver | minikube start --driver=podman --network-plugin=cni |
Open dashboard | minikube dashboard |
SSH into node | minikube ssh |
Enable metrics-server | minikube addons enable metrics-server |
Upgrade Minikube (macOS) | minikube delete && brew upgrade minikube |
π Further reading¶
-
Minikube Quick Start guide (official) https://minikube.sigs.k8s.io/docs/start/
-
Minikube Docker driver docs https://minikube.sigs.k8s.io/docs/drivers/docker/
-
Enable NGINX Ingress in Minikube https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/
-
Load / cache images inside Minikube https://minikube.sigs.k8s.io/docs/handbook/pushing/
-
Using Minikube's built-in kubectl https://minikube.sigs.k8s.io/docs/handbook/kubectl/
-
Allocate max CPU/RAM flags https://minikube.sigs.k8s.io/docs/faq/#how-can-i-allocate-maximum-resources-to-minikube
-
Ingress-DNS addon overview https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns/
-
Stack Overflow: loading local images into Minikube https://stackoverflow.com/questions/42564058/how-can-i-use-local-docker-images-with-minikube
Minikube gives you the fastest, vendor-neutral sandbox for experimenting with MCP Gateway-and everything above doubles as CI instructions for self-hosted GitHub runners or ephemeral integration tests.