IVIA Launchpad
Chapter 3

Local Setup with Minikube

Install Docker-compatible tooling, kubectl, Helm, and Minikube on macOS, Windows, or Linux, then verify a local cluster.

Just started Saved in this browser.

A local cluster gives you a safe Kubernetes laboratory. Minikube creates one node on your computer and configures kubectl to talk to it. Completing this chapter removes “works on my machine” surprises before you build images.

Last updated: 2026-07-20

Audience

Who this chapter is for

This chapter is for beginners who can install software with administrator rights on their laptop. Choose one OS path (macOS, Windows, or Linux). No prior Kubernetes experience is assumed.

Step by step

Download this chapter's files

Use your browser to download either ivia-chapter-03.tar.gz or ivia-chapter-03.zip. The archive is self-contained; you do not need this tutorial repository.

Open a terminal after the browser download:

cd ~/Downloads
tar -xzf ivia-chapter-03.tar.gz
cd ivia-chapter-03

All remaining relative paths in this chapter start from that extracted directory.

Do this

The challenge

Challenge: start one healthy Minikube cluster and prove that Docker, Minikube, kubectl, and Helm all answer from your terminal.

Prepare

Prerequisites

Required

  • A 64-bit macOS, Windows, or Linux computer.
  • At least 2 CPUs, 2 GB free memory, 20 GB free disk, and internet access. Four CPUs and 6 GB memory are more comfortable.
  • Administrator access for installation.
  • Hardware virtualization enabled when using a VM-based driver.
  • Docker Engine or Docker Desktop (required for the Minikube docker driver used here).
  • kubectl, Helm 3, and Minikube (installed below).

Optional

  • A preferred code editor (VS Code, Cursor, or similar).
  • Extra CPU or memory allocations in Docker Desktop if you keep many apps open.
Outcome

Learning goals

After this chapter, you will be able to:

  • Install a container runtime, Minikube, kubectl, and Helm
  • Start and inspect a local cluster
  • Label the node for compatibility with generic chart 4.8.0
  • Run a tiny container smoke test
  • Stop the cluster without deleting your work
Step by step

Install the tools

Install Homebrew first, then run:

brew install --cask docker
brew install minikube kubectl helm
open -a Docker

Wait until Docker Desktop reports that its engine is running. Apple Silicon and Intel are both supported by Homebrew's packages.

Step by step

Smoke-test the container runtime

We run a tiny official image so Docker works before Minikube starts.

docker run --rm hello-world

You should see a message that begins with Hello from Docker!. If this fails, fix Docker before continuing.

Step by step

Start and verify on every platform

We start Minikube with the docker driver so the cluster shares Docker’s engine on your machine.

docker version
minikube start --driver=docker --cpus=2 --memory=4096
kubectl cluster-info
kubectl get nodes
helm version

Expected sanity checks:

  • docker version prints Client and Server sections without connection errors.
  • kubectl get nodes shows one node named minikube with status Ready.
  • helm version prints a v3 version string.

Chart 4.8.0 avoids build nodes and prefers app nodes. Label the Minikube node explicitly so its scheduling rule is unambiguous:

kubectl label node minikube ivia.ch/nodetype=app --overwrite
kubectl get node minikube --show-labels

You should see ivia.ch/nodetype=app in the label list. Create a namespace used by later chapters:

kubectl create namespace tutorial --dry-run=client -o yaml | kubectl apply -f -

Pause work without deleting it:

minikube stop

Resume later with minikube start. Do not run minikube delete unless you intend to remove workloads and local volumes.

Verify

Expected validation

kubectl get nodes should show one node named minikube with status Ready. helm version should print a v3 version. The label output should include ivia.ch/nodetype=app, and this should print Active:

kubectl get namespace tutorial -o jsonpath='{.status.phase}'; echo
Troubleshoot

Troubleshooting and common pitfalls

  • Docker daemon not reachable: start Docker Desktop or sudo systemctl start docker; on Linux, verify your group membership with groups after logging in again.
  • Docker Desktop fails to start: check Virtualization/WSL 2 settings, free disk space, and Docker Desktop’s Troubleshoot → Restart.
  • Not enough memory: lower --memory to 3072, close heavy applications, or adjust Docker Desktop's resource limit.
  • Wrong kubectl context: run kubectl config current-context; it should be minikube. Correct it with kubectl config use-context minikube.
  • Windows command not found after install: close and reopen PowerShell so its PATH refreshes.
  • ARM versus x86 package mismatch: check uname -m on macOS/Linux or $env:PROCESSOR_ARCHITECTURE in PowerShell.
  • Existing cluster uses another driver: inspect minikube profile list; keep the working profile instead of repeatedly recreating it.
Practice

Recap and practice

Recap: You installed the required tools, verified Docker with hello-world, started Minikube, labeled the node, and created the tutorial namespace.

Try to explain in your own words:

  1. What does kubectl talk to after minikube start?
  2. Why label the node with ivia.ch/nodetype=app?

Exercise: Run kubectl config current-context and confirm it prints minikube.

Stretch: Increase Minikube memory to 6144 on a restart (minikube start --memory=6144) and note whether kubectl get nodes still reports Ready.

Reference

Official references

Just started Saved in this browser.