This guide walks you through setting up your local environment for the CleanStart labs and tutorials. We provide four options ranging from minimal (Docker only) to complete (full development environment), so you can choose what fits your needs and timeline.
What You Need Before Starting
Option | Setup Time | Best For | Labs Supported |
|---|---|---|---|
A: Docker Only | 10 min | Getting started quickly | 1-4 |
B: Docker + kind | 20 min | Kubernetes exploration | 1-6 |
C: Full Lab Environment | 30 min | Advanced labs, local testing | All labs |
D: Cloud-Based | 15 min | No local installation | All labs |
System Requirements
Minimum Requirements (Any Option)
For the minimum requirements, you need at least 2+ CPU cores (though 4+ cores are recommended for Options B, C, and D), 4GB of RAM (with 8GB+ recommended for Options B, C, and D), 20GB of available disk space, an operating system of macOS 11 or higher, Windows 10/11 with WSL2, or Linux such as Ubuntu 20.04 or later, and an internet connection that is required for downloading images and tools.
Recommended Specifications
The recommended specifications include 4+ CPU cores, 16GB of RAM, 50GB of disk space, and a stable network connection since container images can be quite large.
Option A: Docker Desktop Only (10 minutes)
This is the fastest option. Use it if you're new to containers and want to get started immediately, or if you only plan to work through Labs 1-4 (which focus on container fundamentals).
Installation Steps
macOS
# Download from Docker website or use Homebrewbrew install docker # Start Docker Desktopopen /Applications/Docker.app # Verify installation (wait 1-2 minutes for Docker daemon)docker run hello-worldWindows (WSL2)
- Install WSL2 and a Linux distribution (Ubuntu recommended)
- Download Docker Desktop from docker.com/products/docker-desktop
- Install and launch Docker Desktop
- Enable "Use the new Virtualization architecture" in Settings → Advanced
# Verify in PowerShelldocker run hello-worldLinux (Ubuntu/Debian)
# Install Dockercurl -fsSL https://get.docker.com -o get-docker.shsudo sh get-docker.sh # Add user to docker group (requires logout/login)sudo usermod -aG docker $USERnewgrp docker # Verifydocker run hello-worldVerification for Option A
# Check Docker versiondocker --version# Expected: Docker version 20.10+ # Check Docker daemondocker ps# Expected: Empty list of containers (no errors) # Pull a test imagedocker pull nginx:alpinedocker run -d --name test-nginx nginx:alpinedocker ps# Expected: test-nginx running # Cleanupdocker stop test-nginxdocker rm test-nginxWhat You Can Do
With Option A, you can run and customize containers, build Docker images, work with registries such as registry.cleanstart.com and docker.io, and complete Labs 1-4.
Not Included
Option A does not include Kubernetes support (Pods, Services, Deployments), Helm charts, or multi-node orchestration capabilities.
Option B: Docker + kind (20 minutes)
This option adds Kubernetes to your setup. Use it if you want to explore container orchestration or plan to work through Labs 5-6.
Prerequisites
You should complete Option A setup first to ensure Docker Desktop is running, have 4GB or more of RAM available, and have at least 15GB of disk space.
Installation Steps
macOS
# Install kind (Kubernetes in Docker)brew install kind # Install kubectl (Kubernetes CLI)brew install kubectl # Verify installationskind versionkubectl version --clientWindows (WSL2)
# In Windows PowerShell (admin)choco install kind kubectl # Or download manually from:# - kind: https://kind.sigs.k8s.io/docs/user/quick-start/#installation# - kubectl: https://kubernetes.io/docs/tasks/tools/ # Verify in WSL2 terminalkind versionkubectl version --clientLinux
# Install kindcurl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-linux-amd64chmod +x ./kindsudo mv ./kind /usr/local/bin/kind # Install kubectlcurl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"chmod +x kubectlsudo mv kubectl /usr/local/bin/kubectl # Verifykind versionkubectl version --clientCreate Your First Cluster
# Create a cluster named cleanstart-labkind create cluster --name cleanstart-lab # Verify the cluster existskubectl get nodes# Expected: One node named cleanstart-lab-control-plane # Check pods in system namespaceskubectl get pods --all-namespaces# Expected: coredns, etcd, kube-apiserver, kube-controller-manager, kube-proxy, kube-schedulerVerification for Option B
# Run a test deploymentkubectl create deployment nginx --image=nginx:alpinekubectl expose deployment nginx --port=80 --type=LoadBalancer # Check the deploymentkubectl get deploymentskubectl get podskubectl get services # Clean upkubectl delete service nginxkubectl delete deployment nginxWhat You Can Do
With Option B, you can deploy Kubernetes manifests, work with Pods and Deployments, explore Services and networking, and complete Labs 1-6.
Not Included
Option B does not include image signing and verification tools like cosign, advanced image inspection tools like crane, or local package management capabilities.
Option C: Full Lab Environment (30 minutes)
This is the complete setup with all tools needed for advanced labs. Use this if you plan to work through all labs or need to test image security features.
Prerequisites
You should complete Option B setup first to ensure Docker and kind are running, have 4 or more CPU cores, 16GB or more of RAM, and at least 50GB of disk space.
Additional Tools Installation
cosign (Image Signature Verification)
# macOSbrew install cosign # Windows (in WSL2)COSIGN_VERSION=v2.2.4curl -fsSL https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64 -o /usr/local/bin/cosignchmod +x /usr/local/bin/cosign # LinuxCOSIGN_VERSION=v2.2.4curl -fsSL https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64 -o /usr/local/bin/cosignchmod +x /usr/local/bin/cosign # Verifycosign versioncrane (Container Registry Tool)
# macOSbrew install crane # Windows/Linuxgo install github.com/google/go-containerregistry/cmd/crane@latest# Ensure $HOME/go/bin is in PATHexport PATH=$PATH:$HOME/go/bin # Verifycrane versionjq (JSON Query)
# macOSbrew install jq # Windowschoco install jq # Linux (Ubuntu/Debian)sudo apt-get install jq # Verifyjq --versionyq (YAML Query)
# macOSbrew install yq # Windowschoco install yq # Linuxsudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64sudo chmod +x /usr/local/bin/yq # Verifyyq --versiongit (Version Control)
# macOSbrew install git # Windowschoco install git# Or download from https://git-scm.com/download/win # Linux (usually pre-installed)sudo apt-get install git # Verifygit --versionVerification for Option C
# Check all tools are availabledocker --versionkubectl version --clientkind versioncosign versioncrane versionjq --versionyq --versiongit --version # Test cosign connectivitycosign verify-blob --help # Test crane connectivitycrane ls ghcr.io/google/distroless 2>/dev/null || echo "Registry connectivity OK"What You Can Do
With Option C, you can do everything from Options A and B, verify image signatures with cosign, inspect remote images with crane, parse and manipulate JSON and YAML data, clone and manage repositories, and complete all advanced labs.
Not Included
Option C does not include a specific IDE or editor (you should bring your own) or advanced CI/CD tools like GitHub Actions.
Option D: Cloud-Based (15 minutes)
Zero local installation needed. Use cloud-provided development environments.
GitHub Codespaces
Recommended: Simple, integrated with GitHub, most straightforward.
- Go to https://github.com/codespaces
- Click "Create codespace on main" from CleanStart repo
- Wait 2-3 minutes for environment to be ready
- All tools are pre-configured
What's Included: Docker, kubectl, kind, cosign, crane, jq, yq, git
# Inside the Codespace terminal, verifydocker --versionkubectl --versionkind --versioncosign --versioncrane --versionGitpod
Alternative cloud option: Browser-based development environment.
- Click "Open in Gitpod" from CleanStart repo (if available) or use: https://gitpod.io/#https://github.com/cleanstart/cleanstart
- Wait 2-3 minutes for initialization
- All tools are pre-configured
# Inside Gitpod terminal, verifydocker --versionkubectl --versionkind --versionRunning Labs in Cloud Environment
# Create kind cluster in cloud environmentkind create cluster --name cleanstart-lab # Deploy test applicationkubectl apply -f https://raw.githubusercontent.com/cleanstart/cleanstart/main/examples/simple-nginx.yaml # Verify deploymentkubectl get podskubectl get servicesAdvantages
Cloud-based option offers several benefits: no local resources are consumed on your machine, you get browser-accessible VS Code for editing, your work is auto-saved in GitHub, and the environment is consistent across your entire team.
Limitations
Using a cloud-based option requires a GitHub account and potentially paid Codespaces for usage exceeding 60 hours per month, the environment is entirely network-dependent, and it may be slower than running Docker locally.
Ready Check Script
Save this script as ready-check.sh in your lab folder and run it to verify your entire environment:
#!/bin/bashset -e echo "=== CleanStart Lab Environment Ready Check ==="echo "" # Define color codesGREEN='\033[0;32m'RED='\033[0;31m'YELLOW='\033[1;33m'NC='\033[0m' # No Color # Check Dockerecho -n "Checking Docker... "if command -v docker &> /dev/null; then DOCKER_VERSION=$(docker --version | awk '{print $3}' | sed 's/,//') echo -e "${GREEN}✓${NC} $DOCKER_VERSION"else echo -e "${RED}✗ Not installed${NC}" exit 1fi # Check Docker daemonecho -n "Checking Docker daemon... "if docker ps &> /dev/null; then echo -e "${GREEN}✓${NC} Running"else echo -e "${RED}✗ Not running or not accessible${NC}" exit 1fi # Check kubectl (optional for Options A)echo -n "Checking kubectl... "if command -v kubectl &> /dev/null; then KUBECTL_VERSION=$(kubectl version --client --short 2>/dev/null | grep -oP '(?<=v)[0-9]+\.[0-9]+' || echo "unknown") echo -e "${GREEN}✓${NC} $KUBECTL_VERSION"else echo -e "${YELLOW}⚠${NC} Not installed (required for Options B-D)"fi # Check kind (optional for Options A)echo -n "Checking kind... "if command -v kind &> /dev/null; then KIND_VERSION=$(kind version | awk '{print $2}') echo -e "${GREEN}✓${NC} $KIND_VERSION"else echo -e "${YELLOW}⚠${NC} Not installed (required for Options B-D)"fi # Check cosign (optional for Option C)echo -n "Checking cosign... "if command -v cosign &> /dev/null; then COSIGN_VERSION=$(cosign version 2>/dev/null | head -1 || echo "unknown") echo -e "${GREEN}✓${NC} Installed"else echo -e "${YELLOW}⚠${NC} Not installed (required for Option C)"fi # Check crane (optional for Option C)echo -n "Checking crane... "if command -v crane &> /dev/null; then echo -e "${GREEN}✓${NC} Installed"else echo -e "${YELLOW}⚠${NC} Not installed (required for Option C)"fi # Check jq (optional for Option C)echo -n "Checking jq... "if command -v jq &> /dev/null; then JQ_VERSION=$(jq --version) echo -e "${GREEN}✓${NC} $JQ_VERSION"else echo -e "${YELLOW}⚠${NC} Not installed (optional)"fi # Check yq (optional for Option C)echo -n "Checking yq... "if command -v yq &> /dev/null; then YQ_VERSION=$(yq --version) echo -e "${GREEN}✓${NC} $YQ_VERSION"else echo -e "${YELLOW}⚠${NC} Not installed (optional)"fi # Check gitecho -n "Checking git... "if command -v git &> /dev/null; then GIT_VERSION=$(git --version | awk '{print $3}') echo -e "${GREEN}✓${NC} $GIT_VERSION"else echo -e "${YELLOW}⚠${NC} Not installed (optional)"fi # Check disk spaceecho -n "Checking disk space... "AVAILABLE_GB=$(df . | tail -1 | awk '{printf "%.1f", $4/(1024*1024)}')if (( $(echo "$AVAILABLE_GB > 20" | bc -l) )); then echo -e "${GREEN}✓${NC} ${AVAILABLE_GB}GB available"else echo -e "${YELLOW}⚠${NC} Only ${AVAILABLE_GB}GB available (20GB recommended)"fi # Check memory (if Linux)if [[ "$OSTYPE" == "linux-gnu"* ]]; then echo -n "Checking available memory... " AVAILABLE_RAM_GB=$(free -h | grep "^Mem:" | awk '{print $7}' | sed 's/G//') if (( $(echo "$AVAILABLE_RAM_GB > 4" | bc -l) )); then echo -e "${GREEN}✓${NC} ${AVAILABLE_RAM_GB}GB available" else echo -e "${YELLOW}⚠${NC} Only ${AVAILABLE_RAM_GB}GB available (8GB+ recommended)" fifi echo ""echo "=== Summary ==="echo -e "${GREEN}✓${NC} Docker (required) - Ready"echo -e "${YELLOW}For additional features:${NC}"echo " - Install kubectl + kind for Kubernetes support (Options B-D)"echo " - Install cosign + crane for image security (Option C)"echo " - Use GitHub Codespaces for cloud-based setup (Option D)"echo ""echo "Choose your setup option from the guide and run specific labs."To use the script:
# Save the scriptcat > ready-check.sh << 'EOF'[paste script above]EOF # Make it executablechmod +x ready-check.sh # Run it./ready-check.shCommon Installation Issues and Fixes
Issue: "Docker daemon is not running" (macOS)
# Solution 1: Start Docker Desktopopen /Applications/Docker.app # Solution 2: Check if Docker socket is accessiblels -la /var/run/docker.sock# If it doesn't exist, Docker isn't running # Solution 3: Reset Docker Desktop# Settings → Advanced → Click "Reset"Issue: "Permission denied while trying to connect to Docker daemon" (Linux)
# Solution: Add user to docker group (requires logout/login)sudo usermod -aG docker $USERnewgrp docker # Verifydocker psIssue: "kind: command not found" (after installation)
# Solution: Add to PATHexport PATH=$PATH:/usr/local/bin # For permanent fix, add to ~/.bashrc or ~/.zshrcecho 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrcsource ~/.bashrcIssue: "failed to get console mode for stdout" (Windows WSL2)
# Solution: Update WSL2 kernelwsl --update # Then restart WSLwsl --shutdownIssue: "Insufficient disk space" during lab
# Check current disk usagedu -sh * # Clean up Docker images/containersdocker system prune -a # WARNING: Removes unused imagesdocker system prune # Safer: removes only stopped containers # Check disk againdf -hIssue: "kind cluster creation timeout"
# Check Docker resourcesdocker stats # Increase Docker memory if needed:# macOS/Windows: Docker Desktop → Preferences → Resources# Then recreate the clusterkind delete cluster --name cleanstart-labkind create cluster --name cleanstart-labIssue: "cosign: command not found" after installation
# Solution: Verify installation locationwhich cosign # If nothing, verify it's in PATHexport PATH=$PATH:$HOME/go/bin # Add permanently to shell profileecho 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrcChoosing Your Setup Option
Start with Option A if you are completely new to containers, want to get running immediately, only have 10 minutes to spare, or plan to work through Labs 1-4 only.
Upgrade to Option B if you understand containers and want to learn Kubernetes, have 20 minutes for setup time, plan to work through Labs 5-6, or have 8GB or more of RAM available.
Go with Option C if you want all tools available, plan to work through all labs, need image security features, or have 16GB or more of RAM with solid disk space.
Use Option D if you don't want to install anything locally, prefer browser-based development, have intermittent local machine access, or have a fast internet connection.
Next Steps
- Choose your setup option from the four above
- Run the Ready Check script to verify installation
- Proceed to the lab tutorials in
/04-build/labs/ - Refer back here if installation issues arise
Once your environment is ready, you're prepared for the hands-on learning experience. The labs are designed to build progressively, so start with Lab 1 and move forward at your own pace.
Additional Resources
For additional information, consult the Docker Documentation at https://docs.docker.com, the Kubernetes Documentation at https://kubernetes.io/docs, the kind Quick Start guide at https://kind.sigs.k8s.io/docs/user/quick-start, Cosign Installation instructions at https://docs.sigstore.dev/cosign/installation/, and GitHub Codespaces information at https://github.com/features/codespaces.
Have questions? Check the troubleshooting section above or refer to the official documentation links.