Docker Compose

While the docker run command is powerful, it can quickly become unwieldy with long strings of volume mounts, environment variables, and platform flags. Docker Compose allows you to define your environment in a simple YAML file.

What is Docker Compose?

Docker Compose is a tool for defining and running multi-container Docker applications. However, in embedded development, we often use it just to simplify running a single complex container setup.

Instead of typing this every time:

docker run --rm -it -v $PWD:/project -w /project --device=/dev/ttyUSB0 espressif/idf:release-v5.1

You define a docker-compose.yml file, and simply run:

docker-compose run --rm esp-idf

Creating a docker-compose.yml

Let's look at a typical docker-compose.yml file for an ESP-IDF project. Create a file named docker-compose.yml in the root of your project:

1version: '3.8'
2
3services:
4  esp-idf:
5    image: espressif/idf:release-v5.1
6    volumes:
7      - .:/project
8    working_dir: /project
9    # Optional: For Linux users to pass the USB device for flashing
10    # devices:
11    #   - "/dev/ttyUSB0:/dev/ttyUSB0"
12    command: /bin/bash

Breaking it down:

• version: The version of the Compose file format.
• services: Defines the different containers. We have one service named esp-idf.
• image: The Docker image to use (the official ESP-IDF image).
• volumes: Maps the current directory (.) on your host to /project inside the container. This is crucial: it means code you edit on your host is immediately visible inside the container, and binaries compiled in the container are saved to your host.
• working_dir: Sets the default directory when the container starts.
• devices: (Linux only) Maps the USB device for flashing.
• command: The default command to run. We launch a bash shell.

Common Commands

Open a shell inside the container

This is the most common workflow. It opens an interactive terminal inside the container where you can run idf.py build.

docker-compose run --rm esp-idf

(The --rm flag removes the container instance when you exit, keeping your system clean).

Run a single command and exit

If you just want to build without opening an interactive shell:

docker-compose run --rm esp-idf idf.py build