How to Install Minikube (Mac • Windows • Linux)

Minikube Setup (for make ci + make cd)

0) Prereqs

  • Docker Desktop (Mac/Windows) or Docker Engine (Linux)
  • Minikube
  • Make (Windows: use Git Bash or install via Chocolatey/Scoop)
  • (Optional) cosign if you want to sign/verify images

Verify:

docker --version
minikube version
kubectl version --client
make -v

1) Install Minikube

macOS

brew install minikube

Windows (PowerShell as Admin)

choco install minikube
# or: winget install minikube

Linux (Debian/Ubuntu example)

sudo apt-get update && sudo apt-get install -y curl conntrack
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

2) Start a local cluster

We use a dedicated profile called ship so it doesn’t collide with other setups.

Recommended driver: Docker (works on Mac/Windows/Linux)

minikube start -p ship --driver=docker --cpus=2 --memory=4096
minikube -p ship status

Windows (Hyper-V alternative, if Docker Desktop isn’t available):

minikube start -p ship --driver=hyperv --cpus=2 --memory=4096

Tip: If you’ve got 16GB+ RAM, bump to --cpus=4 --memory=6144 for a smoother experience.

3) Point kubectl at Minikube & create the namespace

kubectl config use-context minikube
kubectl get nodes
kubectl create namespace ship || true

Pre-pull common tool images so the class is fast even offline:

docker pull returntocorp/semgrep:latest
docker pull zricethezav/gitleaks:latest
docker pull bridgecrew/checkov:latest
docker pull hadolint/hadolint:latest
docker pull aquasec/trivy:latest
docker pull anchore/syft:latest
docker pull zaproxy/zap-stable:latest

(Or use the warm-cache target below.)

5) Run it

From the repo root:

make ci          # builds & scans locally -> artifacts/
make cd          # starts Minikube (if needed), loads image, applies K8s, verifies
make k8s-port    # prints a URL to hit the app via Minikube

Open the printed URL (e.g., http://127.0.0.1:xxxxx) and try:

  • /
  • /healthz
  • /echo?input=<script>alert(1)</script> (intentional XSS for the lab)

6) Useful Make targets (paste into your Makefile)

Doctor / dashboard / cache warm-up

mk-doctor:
	@echo "== Minikube doctor =="
	minikube -p $(PROFILE) status || true
	kubectl get nodes
	kubectl -n $(NAMESPACE) get deploy,svc || true

mk-dashboard:
	@echo "== Minikube dashboard (opens browser) =="
	minikube -p $(PROFILE) dashboard --url &

warm-cache:
	@echo "== Pre-pulling common tool images =="
	docker pull returntocorp/semgrep:latest
	docker pull zricethezav/gitleaks:latest
	docker pull bridgecrew/checkov:latest
	docker pull hadolint/hadolint:latest
	docker pull aquasec/trivy:latest
	docker pull anchore/syft:latest
	docker pull zaproxy/zap-stable:latest

Then run: make warm-cache and make mk-doctor.

7) Troubleshooting quick hits

A) Can’t get a service URL (make k8s-port prints nothing)

  • Ensure the app was deployed:

    kubectl -n ship get deploy app
kubectl -n ship get svc app

  • Re-apply:

    make k8s-apply && make k8s-verify
make k8s-port

B) ZAP image not found / old name

  • We use zaproxy/zap-stable:latest. If you still have owasp/zap2docker-stable, update the Makefile (already fixed in the starter).

C) Syft CLI changed flags

  • Use the new syntax in the Makefile:

    docker run --rm -v $(PWD):/work anchore/syft:latest \
    scan dir:/work/app -o json > artifacts/sbom.json

D) Very slow image loads

  • Confirm Docker driver: minikube start -p ship --driver=docker
  • We use minikube image load (no registry needed). Avoid docker system prune during the course.

E) Windows path/volume issues

  • Run the repo from your user directory (e.g., C:\Users\<you>\...) so Docker Desktop can mount volumes.
  • Use Git Bash or PowerShell. If you see permission or mount errors, restart Docker Desktop and Minikube.

F) DNS/network hiccups inside Minikube

  • Restart Docker Desktop, then:

    minikube -p ship stop && minikube -p ship start

  • As a last resort:

    make mk-delete && make mk-up

G) Apple Silicon (M1/M2/M3)

  • All images referenced are multi-arch. Docker Desktop handles arm64 transparently.

8) Nice-to-have Minikube add-ons (optional)

  • Dashboard (already wrapped by make mk-dashboard)

  • Ingress if you want nicer hostnames locally:

    minikube -p ship addons enable ingress

    (Not required for this starter; minikube service ... --url is simpler and cross-platform.)

9) Clean up

make mk-down     # stop cluster
make mk-delete   # delete the 'ship' profile entirely