Docker Setup¶

This guide walks you through installing Docker and Docker Compose on your system. These are the foundation for running the ESP-IDF development environment in a container.

Why Docker?

Docker ensures every attendee has the exact same toolchain — no version mismatches, no "works on my machine" problems. The pre-built workshop Docker image (provided separately) includes ESP-IDF, the compiler, and all dependencies.

Step 1 — Install Docker Desktop¶

WindowsmacOSLinux (Ubuntu/Debian)

Download Docker Desktop for Windows
Ensure WSL 2 is enabled:
```
wsl --install
```
Run this in an Administrator PowerShell, then restart.
Run the Docker Desktop installer
Restart your computer
Launch Docker Desktop — wait for the engine to start (whale icon in system tray turns steady)

Verify:

docker --version
docker compose version

WSL 2 is required

Docker Desktop on Windows requires WSL 2. If you're on Windows 10, ensure you have build 19044+ or later. Windows 11 has WSL 2 built-in.

Download Docker Desktop for Mac
Drag Docker.app to your Applications folder
Launch Docker from Applications
Wait for the whale icon in the menu bar to stop animating

Verify:

docker --version
docker compose version

Apple Silicon (M1/M2/M3/M4)

Docker Desktop runs Linux ARM64 containers natively on Apple Silicon. The workshop Docker image supports this architecture — no Rosetta needed.

# Remove any old versions
sudo apt-get remove docker docker-engine docker.io containerd runc

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

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

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

# Add your user to the docker group (avoids sudo every time)
sudo usermod -aG docker $USER

# Log out and back in, then verify:
docker --version
docker compose version

Log out after adding to docker group

The usermod -aG docker $USER command takes effect only after you log out and log back in. Otherwise you'll still need sudo for every docker command.

Step 2 — Verify Docker Installation¶

Run the hello-world test to confirm Docker is working:

docker run hello-world

You should see output like:

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

Step 3 — Verify Docker Compose¶

Docker Compose is included with Docker Desktop (Windows/macOS) and the docker-compose-plugin (Linux). Verify:

docker compose version
# Docker Compose version v2.x.x

docker-compose vs docker compose

The older docker-compose (hyphenated) command is deprecated. Use docker compose (space, no hyphen) — it's the V2 plugin that ships with modern Docker.

Step 4 — Allocate Sufficient Resources¶

The ESP-IDF build process is resource-intensive. Ensure Docker has enough CPU and memory allocated.

Docker Desktop (Windows/macOS)Linux

Open Docker Desktop → Settings → Resources
Set CPUs: at least 4
Set Memory: at least 8 GB
Set Swap: at least 2 GB
Click Apply & Restart

Docker Engine on Linux uses system resources directly — no configuration needed. Ensure your system has at least 8 GB RAM.

Step 5 — Create a Working Directory¶

Create a directory where your project files will live. This directory will be mounted into the container so your code persists.

mkdir -p ~/esp-workshop
cd ~/esp-workshop

Docker Compose Quick Reference¶

Once the workshop Docker image is provided, you'll use a docker-compose.yml file to manage the container. Here's a template you'll fill in later:

docker-compose.yml

services:
  esp-idf:
    image: analogdata/esp32s3-devenv:latest  # workshop image (provided later)
    container_name: esp-workshop
    stdin_open: true
    tty: true
    volumes:
      - ./:/workspace
    # devices:  # uncomment when flashing to the board
    #   - /dev/ttyUSB0:/dev/ttyUSB0
    # ports:
    #   - "4040:4040"

Common commands:

Command	Purpose
`docker compose run esp-idf /bin/bash`	Start an interactive shell
`docker compose run esp-idf idf.py build`	Build the project
`docker compose down`	Stop and remove the container
`docker compose ps`	List running containers
`docker compose logs`	View container logs

Troubleshooting¶

Docker daemon not running¶

# Linux
sudo systemctl start docker
sudo systemctl enable docker  # auto-start on boot

# Windows/macOS
# Launch Docker Desktop from your Applications / Start Menu

Permission denied (Linux)¶

sudo usermod -aG docker $USER
# Log out and back in

Out of disk space¶

# Check Docker disk usage
docker system df

# Clean up unused images, containers, and volumes
docker system prune -a

Docker Desktop won't start (Windows)¶

Ensure WSL 2 is installed: wsl --install
Ensure virtualization is enabled in BIOS/UEFI
Restart your computer

Next Steps¶

VS Code Setup → VS Code Setup — Configure your editor for ESP-IDF development
Hardware Kit → Hardware Kit — Reference for all workshop hardware