Skip to main content

Minikube quickstart

1. Start Minikube​

minikube start \
  --cpus=4 \
  --memory=8g \
  --disk-size=30g \
  --kubernetes-version=v1.31.0

minikube addons enable ingress
minikube addons enable storage-provisioner
minikube addons enable metrics-server

# Verify:
kubectl get nodes
# Expect: minikube node Ready

2. Clone the repo + fetch chart deps​

git clone https://github.com/OpenBox-AI/openbox-manifest-k8s-cluster.git
cd openbox-manifest-k8s-cluster

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm dependency update charts/openbox

3. Install OpenBox with the local values profile​

# values-local.yaml — minimal PoC config
global:
  ingress:
    type: nginx
    className: nginx
    domain: openbox.local

# Skip GPU workloads
guardrails-api:
  llamafirewall:
    enabled: false

# Use in-cluster Postgres (Bitnami)
postgresql:
  enabled: true
  auth:
    postgresPassword: local-poc-only-do-not-use-in-prod
    password: local-poc-only-do-not-use-in-prod

# Keycloak bootstrap creds
identity-service:
  secret:
    stringData:
      KC_DB_PASSWORD: local-poc-only-do-not-use-in-prod
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin

# Skip Argo Rollouts (Minikube doesn't have CRDs by default)
openbox-guardrails-service:
  rollout:
    enabled: false

# Down-sized for laptop
openbox-backend:  { autoscaling: { minReplicas: 1, maxReplicas: 1 } }
openbox-core:     { autoscaling: { minReplicas: 1, maxReplicas: 1 } }
openbox-fe:       { autoscaling: { minReplicas: 1, maxReplicas: 1 } }
guardrails-api:   { autoscaling: { minReplicas: 1, maxReplicas: 1 } }
identity-service: { autoscaling: { minReplicas: 1, maxReplicas: 1 } }

Install:

kubectl create namespace openbox

helm upgrade --install openbox charts/openbox \
  -n openbox \
  -f values-local.yaml \
  --atomic --wait --timeout 10m

kubectl get pods -n openbox
# Expect ~6-8 pods Running/Ready

4. Add local DNS​

echo "$(minikube ip) openbox.local" | sudo tee -a /etc/hosts

5. Open the UI​

open http://openbox.local/     # macOS
xdg-open http://openbox.local/ # Linux

Log in with the bootstrap creds:

  • User: admin (from KC_BOOTSTRAP_ADMIN_PASSWORD)
  • Realm: master

6. Uninstall​

helm uninstall openbox -n openbox
minikube delete

Faster iterations — kind-smoke script​

For repeated smoke tests, the repo ships scripts/kind-smoke.sh (uses kind, not Minikube — but the flow is similar). Adapt for Minikube if preferred.

Troubleshooting​

Pods stuck in Pending — laptop is out of RAM. Increase --memory=12g in minikube start.

ImagePullBackOff — Minikube can't reach ghcr.io. Verify network + DNS. Optionally pre-load:

docker pull ghcr.io/openbox-ai/openbox-backend:0.1.0
minikube image load ghcr.io/openbox-ai/openbox-backend:0.1.0

Ingress returns 404 — /etc/hosts entry missing or ingress addon not enabled.

See S2 troubleshooting for more common issues (same chart, same failure modes).

Next​