Skip to main content

Docker Installation Guide

Docker is a platform for developing, shipping, and running applications in containers. This guide covers installation on Windows 11, macOS, and Linux.

Trademark Notice

Docker® and the Docker logo are trademarks of Docker, Inc. All trademarks and logos are used for representation purposes only. No prior copyright or trademark authorization has been obtained. This documentation is for educational purposes only.

System Requirements​

Windows 11​

  • Windows 11 64-bit: Pro, Enterprise, or Education
  • WSL 2 enabled
  • Hyper-V and Containers Windows features enabled
  • 4GB system RAM minimum

macOS​

  • macOS 11 or newer
  • Apple Silicon (M1/M2) or Intel chip
  • 4GB RAM minimum

Linux​

  • 64-bit kernel and CPU support
  • Kernel version 3.10 or higher
  • iptables version 1.4 or higher

Windows 11 Installation​

Step 1: Enable WSL 2​

# Run PowerShell as Administrator
wsl --install

Restart your computer after installation.

Step 2: Download Docker Desktop​

  1. Visit Docker Desktop for Windows
  2. Download the installer
  3. Run Docker Desktop Installer.exe
  4. Follow the installation wizard
  5. Ensure "Use WSL 2 instead of Hyper-V" is checked

Step 3: Start Docker Desktop​

  1. Launch Docker Desktop from Start menu
  2. Accept the service agreement
  3. Wait for Docker Engine to start

Step 4: Verify Installation​

docker --version
docker run hello-world

Troubleshooting Windows​

Issue: WSL 2 installation failed

# Enable required Windows features
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# Set WSL 2 as default
wsl --set-default-version 2

Issue: Docker Desktop won't start

  • Check Windows Defender Firewall settings
  • Ensure virtualization is enabled in BIOS
  • Run: netsh winsock reset in Administrator PowerShell

macOS Installation​

Step 1: Choose Your Architecture​

For Apple Silicon (M1/M2/M3):

  • Download Docker Desktop for Apple Silicon

For Intel Macs:

  • Download Docker Desktop for Intel chip

Step 2: Install Docker Desktop​

# Download via command line (Apple Silicon example)
curl -O https://desktop.docker.com/mac/main/arm64/Docker.dmg

# Or visit: https://www.docker.com/products/docker-desktop/
  1. Open the downloaded .dmg file
  2. Drag Docker icon to Applications folder
  3. Launch Docker from Applications
  4. Authorize with your password

Step 3: Configure Docker Desktop​

  1. Open Docker Desktop
  2. Go to Preferences → Resources
  3. Adjust CPU, Memory, and Disk as needed
  4. Click "Apply & Restart"

Step 4: Verify Installation​

docker --version
docker run hello-world

Homebrew Installation (Alternative)​

# Install using Homebrew
brew install --cask docker

# Start Docker
open /Applications/Docker.app

Troubleshooting macOS​

Issue: "Docker Desktop requires macOS 11 or newer"

  • Update macOS to latest version
  • Check: System Preferences → Software Update

Issue: Performance issues

# Adjust resources in Docker Desktop preferences
# Recommended settings:
# CPUs: 4
# Memory: 8GB
# Swap: 2GB

Linux Installation​

Docker supports most Linux distributions. Here are the most common ones:

Ubuntu / Debian​

Step 1: Remove Old Versions​

sudo apt-get remove docker docker-engine docker.io containerd runc

Step 2: Set Up Repository​

# Update package index
sudo apt-get update

# Install prerequisites
sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

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

Step 3: Install Docker Engine​

# Update package index
sudo apt-get update

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

# Verify installation
sudo docker --version

Step 4: Post-Installation Steps​

# Create docker group
sudo groupadd docker

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

# Activate changes
newgrp docker

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

# Verify without sudo
docker run hello-world

RHEL / CentOS / Fedora​

# Remove old versions
sudo dnf remove docker \
    docker-client \
    docker-client-latest \
    docker-common \
    docker-latest \
    docker-latest-logrotate \
    docker-logrotate \
    docker-engine

# Install using repository
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

# Install Docker Engine
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Start Docker
sudo systemctl start docker
sudo systemctl enable docker

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

# Verify
docker --version
docker run hello-world

Arch Linux​

# Install Docker
sudo pacman -S docker docker-compose

# Start and enable Docker
sudo systemctl start docker.service
sudo systemctl enable docker.service

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

# Verify
docker --version

Troubleshooting Linux​

Issue: Permission denied

# Check if user is in docker group
groups $USER

# If not, add and re-login
sudo usermod -aG docker $USER
newgrp docker

Issue: Docker daemon not starting

# Check status
sudo systemctl status docker

# View logs
sudo journalctl -xu docker

# Restart service
sudo systemctl restart docker

Docker Compose Installation​

Windows & macOS​

Docker Compose is included with Docker Desktop.

Linux​

# Docker Compose is now a plugin, installed with docker-compose-plugin

# Verify installation
docker compose version

# If not installed
sudo apt-get install docker-compose-plugin

# Or download standalone binary
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Verification & Testing​

Basic Commands​

# Check version
docker --version
docker compose version

# Run test container
docker run hello-world

# List running containers
docker ps

# List all containers
docker ps -a

# List images
docker images

# System info
docker info

Test Docker Compose​

Create docker-compose.yml:

version: '3.8'

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

Run:

docker compose up -d
curl http://localhost:8080
docker compose down

Post-Installation Best Practices​

1. Configure Logging​

# Edit /etc/docker/daemon.json
sudo tee /etc/docker/daemon.json <<EOF
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

sudo systemctl restart docker

2. Set Resource Limits​

Docker Desktop (Windows/Mac):

  • Preferences → Resources
  • Set appropriate CPU, Memory, and Disk limits

Linux: Edit /etc/docker/daemon.json:

{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

3. Enable BuildKit​

# Add to ~/.bashrc or ~/.zshrc
export DOCKER_BUILDKIT=1

# Or in daemon.json
{
  "features": {
    "buildkit": true
  }
}

Common Issues & Solutions​

Issue: Disk Space​

# Clean up unused resources
docker system prune -a

# Remove specific items
docker image prune
docker container prune
docker volume prune
docker network prune

Issue: Network Conflicts​

# Change default bridge network
# Edit /etc/docker/daemon.json
{
  "bip": "172.26.0.1/16"
}

sudo systemctl restart docker

Issue: DNS Resolution​

# Add DNS servers to daemon.json
{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Next Steps​

✅ Installed Docker successfully!

Now you can:

Additional Resources​