Troubleshooting Tips

Common issues & fixes

1) Docker Desktop won’t start (Mac/Windows)

  • Ensure virtualization is enabled (Windows: BIOS/UEFI + WSL2).
  • Windows: wsl --install then reboot. In Docker Desktop → Use WSL 2 based engine.
  • Try a factory reset (Docker Desktop Settings → Troubleshoot → Reset to factory defaults).

2) “permission denied” with Docker on Linux

sudo usermod -aG docker $USER
newgrp docker  # or log out/in
docker run --rm hello-world

3) make: command not found

  • macOS: xcode-select --install or brew install make
  • Windows: winget install -e --id GnuWin32.Make (or choco install make)
  • Linux: sudo apt install -y build-essential (Debian/Ubuntu) / dnf install make (Fedora)

4) Minikube won’t start or is slow

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

5) minikube service ... --url prints nothing

  • Ensure Service/Deployment exist:
kubectl -n ship get deploy,svc
  • Reapply:
make k8s-apply

6) Port already in use (app locally)

  • Stop conflicting processes or change port:

    • Docker compose: edit infra/docker/compose.yaml
    • K8s Service: edit infra/k8s/service.yaml (port section)

7) “x509: certificate signed by unknown authority” (corporate proxies)

  • Configure Docker to trust your corp CA.
  • For CLI pulls: docker login to any internal registry if required.
  • Consider setting proxy env vars for the Docker daemon (see Docker docs).

8) Apple Silicon image mismatch

  • Most images are multi-arch. If one isn’t, try:
docker run --platform linux/arm64 ...

9) ZAP cannot reach the app

  • Confirm the URL from:
make k8s-port
  • If still failing, verify the Pod is ready:
kubectl -n ship get pods -o wide
kubectl -n ship describe pod/<name>

10) “permission denied” reading repo (Windows)

  • If using WSL: keep the repo inside your Linux home (\\wsl$\<distro>\home\<you>\...), not on the Windows filesystem, to avoid permission quirks.

Quick resets (safe to run)

# Reset Minikube profile
minikube delete -p ship && minikube start -p ship --driver=docker --cpus=2 --memory=4096

# Nuke dangling tool images and space (be cautious)
docker system df
docker image prune -f

Checklist

  • You can start Docker Desktop (or Docker Engine)
  • minikube start -p ship succeeds; minikube status -p ship is green
  • make ci finishes without errors; artifacts exist
  • make cd deploys; make k8s-port prints a working URL
minikube config view
# (note defaults you might tweak: memory/cpus/driver)