Installation Guide

Install Your Container Tools

Step-by-step guide to setting up Docker, Kubernetes, and all the essential tools you need for container development.

This guide provides detailed installation instructions for Docker and Kubernetes tools across Linux, macOS, and Windows platforms. Follow the steps for your operating system to create a complete container development environment.

Prerequisites

Before beginning installation, ensure your system meets these requirements:

Hardware Requirements

CPU: 64-bit processor with virtualization support
RAM: Minimum 4GB (8GB+ recommended)
Storage: 20GB+ free disk space
Network: Internet connection for downloads

Operating System

Windows: Windows 10/11 (64-bit) Pro, Enterprise, or Education
macOS: macOS 10.15 (Catalina) or newer
Linux: Ubuntu 20.04+, Debian 10+, Fedora 34+, etc.

Additional Requirements

Windows only: WSL2 enabled
Linux only: sudo privileges
All platforms: Terminal/command-line familiarity

Verify Virtualization Support

Virtualization must be enabled in your BIOS/UEFI settings:

To verify on Windows:

systeminfo | findstr "Virtualization"

Should return: "Virtualization Enabled In Firmware: Yes"

To verify on Linux:

grep -E --color 'vmx|svm' /proc/cpuinfo

If the command outputs text, virtualization is supported.

To verify on macOS: Virtualization is enabled by default on modern Macs.

Docker Installation

Docker is the foundation of our containerization journey, allowing you to build and run containers on your local machine.

Docker consists of several components that work together:

Docker Engine: The core runtime that builds and runs containers
Docker CLI: Command-line interface for interacting with Docker
Docker Desktop: GUI application with additional tools (Windows/macOS)
Docker Compose: Tool for defining multi-container applications
Docker Hub: Public registry for sharing container images

Docker uses a client-server architecture where the Docker client communicates with the Docker daemon, which builds, runs, and manages containers.

You have several options for installing Docker:

Docker Desktop: Recommended for Windows and macOS users
Docker Engine: Linux-native installation
Package managers: apt, yum, brew for specific platforms
Convenience script: Quick installation for testing environments
Manual installation: For customized setups

This guide covers the most common and recommended installation methods for each platform.

Docker installation affects your system in several ways:

Creates a Docker daemon process that runs in the background
Adds a docker group for managing permissions (Linux)
Installs a virtual machine (macOS and Windows)
Configures networking interfaces for container connectivity
Allocates disk space for images, containers, and volumes

All of these components can be removed if you later decide to uninstall Docker.

Step 1: Install Docker Engine

Choose your operating system below and follow the installation instructions:

Docker on Linux

Docker runs natively on Linux and can be installed through package repositories:

# Update your package index
sudo apt-get update

# Install prerequisites for apt repositories over HTTPS
sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release \
    software-properties-common

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add the Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update apt with the new repository
sudo apt-get update

# Install Docker Engine and related tools
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Different Linux Distributions

The instructions above are for Ubuntu. For other distributions:

Debian:

Similar to Ubuntu, but use debian instead of ubuntu in URLs

CentOS/RHEL:

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io

Fedora:

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io

Alternative: Quick Installation Script

For testing environments, you can use Docker's convenience script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

The convenience script is great for quick setups but should be reviewed before using in production environments.

#### Features Included in Docker Desktop

Docker Desktop for Mac includes:
- Docker Engine with CLI tools
- Docker Compose for multi-container applications
- Kubernetes (can be enabled in preferences)
- BuildKit for faster image building
- Volume mounting for code and data
- Network port mapping
- Visual Dashboard for container management

Docker Desktop for Windows

Docker Desktop provides an integrated experience on Windows with WSL2 integration:

Enable WSL2 prerequisites

Open PowerShell as Administrator and run:

# Enable WSL and Virtual Machine Platform
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Restart your computer now

Install WSL2 Linux kernel and set as default

Download and install the WSL2 Linux kernel update package
After installation, open PowerShell and run:
wsl --set-default-version 2

Download and install Docker Desktop

Visit Docker Desktop for Windows
Download the installer (.exe)
Run the installer with default settings
Ensure "Use WSL 2 instead of Hyper-V" option is selected

Start Docker Desktop

Launch Docker Desktop from the Start menu
Accept the terms and conditions
Sign in to your Docker Hub account (optional but recommended)
Wait for the Docker service to start

Verify installation

Open PowerShell or Command Prompt and run:

docker --version
docker compose version

Windows Home vs Pro/Enterprise/Education

Docker Desktop works on all editions of Windows 10/11 when using WSL2:

Windows Home: WSL2 backend is your only option
Windows Pro/Enterprise/Education: Can choose between WSL2 or Hyper-V backend

WSL2 generally offers better performance and is recommended for most users.

Docker Desktop Integration with WSL2

When using Docker with WSL2:

Containers run inside the WSL2 Linux kernel
Docker commands work from both Windows and WSL2 Linux distributions
You can develop in your preferred WSL2 distro and run containers natively
Visual Studio Code and other IDEs can connect to your WSL2 environment

Step 2: Verify Docker Installation

After installation, verify that Docker is working correctly with these commands:

# Check Docker version
docker --version

# View detailed system information
docker info

# Run a test container
docker run --rm hello-world

If Docker is installed correctly, the hello-world container will download (if not already present) and run, displaying a success message:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.
...

This verification process confirms that:

The Docker client can connect to the Docker daemon
The daemon can download images from Docker Hub
The daemon can create and run containers
The container output is correctly returned to your terminal

Step 3: Post-Installation Configuration

Complete your Docker setup with these additional configuration steps:

Linux Post-Installation Steps

Configure Docker to run without sudo and start on boot:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Apply the new group membership (or log out and back in)
newgrp docker

# Enable Docker to start on boot
sudo systemctl enable docker.service
sudo systemctl enable containerd.service

# Verify you can run Docker without sudo
docker run --rm hello-world

Adding users to the docker group grants effectively root privileges since containers can mount the host filesystem. Only add trusted users to this group.

Additional Linux Configuration (Optional)

Configure Docker daemon options by creating or editing /etc/docker/daemon.json:

{
  "default-address-pools": [
    {"base": "172.17.0.0/16", "size": 24}
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "features": {
    "buildkit": true
  }
}

After editing, restart Docker:

sudo systemctl restart docker

Kubernetes Tools Installation

Kubernetes allows you to orchestrate containers across multiple hosts. We'll install the essential tools for local Kubernetes development.

Step 1: Install kubectl

kubectl is the command-line tool for interacting with Kubernetes clusters:

Install kubectl on Linux

# Download the latest stable release
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# Validate the binary (optional but recommended)
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check

# Install kubectl
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# Verify installation
kubectl version --client

Alternative installation methods for Linux

Using package manager (Ubuntu/Debian):

# Add Kubernetes apt repository
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Install kubectl
sudo apt-get update
sudo apt-get install -y kubectl

Using snap:

sudo snap install kubectl --classic

Install kubectl on macOS

Using Homebrew (recommended):

brew install kubectl

# Verify installation
kubectl version --client

Using curl:

# Download kubectl binary
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

# Make it executable
chmod +x ./kubectl

# Move to a directory in your PATH
sudo mv ./kubectl /usr/local/bin/kubectl

# Verify installation
kubectl version --client

If you've installed Docker Desktop for Mac and enabled Kubernetes, kubectl is already installed and configured.

Installing kubectl for Apple Silicon Macs

If you're using an M1/M2 Mac, use the arm64 binary instead:

# Using Homebrew (handles architecture automatically)
brew install kubectl

# Or using curl with arm64 architecture
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"
chmod +x ./kubectl
sudo mv ./kubectl /usr/local/bin/kubectl

Install kubectl on Windows

Using Chocolatey (recommended):

choco install kubernetes-cli

# Verify installation
kubectl version --client

Using curl and PowerShell:

# Create a directory for kubectl
mkdir -Path 'C:\kubectl'

# Add this directory to your PATH environment variable
$env:Path += ";C:\kubectl"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::User)

# Download kubectl
curl -LO "https://dl.k8s.io/release/v1.29.0/bin/windows/amd64/kubectl.exe"

# Move kubectl to the directory we created
Move-Item .\kubectl.exe C:\kubectl\kubectl.exe

# Verify installation
kubectl version --client

Using winget:

winget install -e --id Kubernetes.kubectl

If you've installed Docker Desktop for Windows and enabled Kubernetes, kubectl is already installed and configured.

:: ::

Step 2: Install Minikube

Minikube creates a local single-node Kubernetes cluster for development and testing:

Install Minikube on Linux

# Download the latest Minikube binary
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64

# Make it executable and move to a directory in your PATH
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Verify installation
minikube version

Choose a driver for Minikube

Minikube needs a "driver" to create the Kubernetes cluster. On Linux, you have several options:

Docker driver (recommended if Docker is installed):

minikube config set driver docker

KVM driver (requires KVM installation):

# Install KVM
sudo apt-get install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils

# Install the KVM driver for Minikube
curl -LO https://storage.googleapis.com/minikube/releases/latest/docker-machine-driver-kvm2 && \
chmod +x docker-machine-driver-kvm2 && \
sudo mv docker-machine-driver-kvm2 /usr/local/bin/

# Configure Minikube to use KVM
minikube config set driver kvm2

VirtualBox driver (requires VirtualBox installation):

# Install VirtualBox
sudo apt-get install -y virtualbox

# Configure Minikube to use VirtualBox
minikube config set driver virtualbox

Install Minikube on macOS

Using Homebrew (recommended):

brew install minikube

# Verify installation
minikube version

Using curl:

# Download the latest Minikube binary
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64

# Make it executable and move to a directory in your PATH
sudo install minikube-darwin-amd64 /usr/local/bin/minikube

# Verify installation
minikube version

Choose a driver for Minikube

Minikube needs a "driver" to create the Kubernetes cluster. On macOS, you have several options:

Docker driver (recommended if Docker Desktop is installed):

minikube config set driver docker

Hyperkit driver (native macOS hypervisor):

# Install hyperkit driver
brew install hyperkit
brew install minikube-hyperkit-driver

# Configure Minikube to use hyperkit
minikube config set driver hyperkit

VirtualBox driver (requires VirtualBox installation):

# Install VirtualBox
brew install --cask virtualbox

# Configure Minikube to use VirtualBox
minikube config set driver virtualbox

Intel vs. Apple Silicon Macs

For Apple Silicon (M1/M2) Macs:

The Docker driver is recommended and works well
If installing via Homebrew, the ARM64 version is automatically used
Some VM-based drivers may not yet be fully compatible with Apple Silicon

Install Minikube on Windows

Using Chocolatey (recommended):

choco install minikube

# Verify installation
minikube version

Using the installer:

Download the latest Minikube installer
Run the installer
Verify installation by opening Command Prompt or PowerShell and running minikube version

Choose a driver for Minikube

Minikube needs a "driver" to create the Kubernetes cluster. On Windows, you have several options:

Docker driver (recommended with WSL2):

minikube config set driver docker

Hyper-V driver (requires Windows Pro/Enterprise/Education):

# Enable Hyper-V if not already enabled
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

# Configure Minikube to use Hyper-V
minikube config set driver hyperv

VirtualBox driver (requires VirtualBox installation):

# Install VirtualBox via Chocolatey
choco install virtualbox

# Configure Minikube to use VirtualBox
minikube config set driver virtualbox

When using WSL2, the Docker driver provides the best integration and performance.

Step 3: Start Your First Kubernetes Cluster

Now that Minikube is installed, let's create your first local Kubernetes cluster:

# Start Minikube with default settings
minikube start

# Check cluster status
minikube status

# View cluster information
kubectl cluster-info

# View nodes in the cluster
kubectl get nodes

If successful, you should see output similar to:

😄  minikube v1.31.2 on Linux 5.15.0-60-generic
✨  Using the docker driver based on existing profile
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🔄  Restarting existing docker container for "minikube" ...
🐳  Preparing Kubernetes v1.28.3 on Docker 24.0.7 ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: default-storageclass, storage-provisioner
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Customizing Your Cluster

You can customize your Minikube cluster with various options:

# Start with specific Kubernetes version
minikube start --kubernetes-version=v1.28.0

# Allocate more resources
minikube start --cpus=4 --memory=8192MB --disk-size=50GB

# Enable specific addons
minikube start --addons=ingress,dashboard,metrics-server

# Use a specific container runtime
minikube start --container-runtime=containerd

# Create a multi-node cluster
minikube start --nodes=2

# Expose the dashboard
minikube dashboard

Step 4: Install Helm (Optional)

Helm is the package manager for Kubernetes, helping you install and manage applications on your cluster:

Install Helm on Linux

Using script installer (recommended):

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

# Verify installation
helm version

Alternative Installation Methods:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install helm

# CentOS/RHEL
sudo yum install helm

# Snap
sudo snap install helm --classic

Install Helm on macOS

Using Homebrew (recommended):

brew install helm

# Verify installation
helm version

Alternative using the script installer:

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

Install Helm on Windows

Using Chocolatey (recommended):

choco install kubernetes-helm

# Verify installation
helm version

Alternative installation methods:

Scoop: scoop install helm
Download binary: Get the latest release and add it to your PATH

What is Helm and why use it?

Helm helps you manage Kubernetes applications through charts - packages of pre-configured Kubernetes resources:

Package Management: Install, upgrade, and roll back complex applications
Templates: Customize applications for different environments
Repositories: Share and reuse configurations
Release Management: Track and manage application versions

Helm simplifies deploying applications that consist of many Kubernetes resources.

Additional Tools (Optional)

Consider these additional tools to enhance your Kubernetes development experience:

Kubernetes Dashboard

A web-based UI for Kubernetes clusters

# Enable the dashboard in Minikube
minikube addons enable dashboard

# Access the dashboard
minikube dashboard

Lens

An IDE for KubernetesDownload from k8slens.dev

kubectx & kubens

Tools for switching between contexts and namespaces

# Install on Linux/macOS
brew install kubectx

# Install on Windows
choco install kubectx

k9s

Terminal UI for Kubernetes

# Install on Linux/macOS
brew install k9s

# Install on Windows
choco install k9s

Verifying Your Installation

Now that you've installed all the necessary components, let's verify that everything is working correctly by performing some basic tests. This will ensure your development environment is properly set up before you start building applications.

Step 1: Verify Docker

Let's first confirm that Docker is functioning properly by running a few simple commands:

# Run a simple container and verify output
docker run --rm alpine echo "Hello from Docker container!"

This command pulls the lightweight Alpine Linux image (if not already present) and runs a container that displays a hello message. The --rm flag ensures the container is automatically removed after execution.

# List running containers to verify Docker daemon is responsive
docker ps

You should see a list of running containers (which might be empty if you don't have any containers running).

# Create a simple Docker network to test network functionality
docker network create test-network

# Verify the network was created
docker network ls | grep test-network

# Remove the test network when done
docker network rm test-network

If these commands execute without errors, your Docker installation is working correctly.

If you see "Hello from Docker container!" as output from the first command, Docker is successfully pulling images and running containers. The network commands verify that Docker's networking capabilities are functioning properly.

Step 2: Verify Kubernetes

Now, let's verify that your Kubernetes cluster is running and can deploy applications:

# Check that Minikube is running with proper status
minikube status

You should see output indicating that Minikube is running, with the host, kubelet, and apiserver all showing "Running" status.

# Deploy a simple test application to your cluster
kubectl create deployment hello-kubernetes --image=k8s.gcr.io/echoserver:1.4

# Expose the deployment as a NodePort service
kubectl expose deployment hello-kubernetes --type=NodePort --port=8080

# Wait a moment for the pod to be ready
kubectl wait --for=condition=ready pod -l app=hello-kubernetes --timeout=60s

Let's check what we've created:

# Verify the pod is running
kubectl get pods -l app=hello-kubernetes

# Examine the created service
kubectl get services hello-kubernetes

# Get detailed information about our deployment
kubectl describe deployment hello-kubernetes

Finally, let's access our application:

# Open the service in your default browser
minikube service hello-kubernetes

If everything is working correctly, your browser should open automatically and display the echoserver application. This confirms that your Kubernetes cluster can successfully:

Deploy container images
Create pods from deployments
Expose services to the network
Route traffic to the correct pods

Step 3: Clean Up Test Resources

Once you've verified everything is working, let's clean up the test resources:

# Delete the service we created
kubectl delete service hello-kubernetes

# Delete the deployment
kubectl delete deployment hello-kubernetes

# Verify resources were removed
kubectl get all | grep hello-kubernetes

The last command should return no results, indicating all resources have been successfully removed.

It's good practice to clean up test resources when they're no longer needed to avoid cluttering your cluster and consuming unnecessary resources.

Next Steps

Now that you have a working Docker and Kubernetes environment, you're ready to start building, deploying, and managing production containerized workloads!