Document the build command with Docker Compose

Your Dockerfile properly documents the steps to produce an image. But how do you document the build command to produce the image? This post shows how to document the build command with Docker Compose.

The primary purpose of Docker Compose is managing a multi-tier specified in compose.yaml (or formerly docker-compose.yml). This includes building the necessary images for the individual components defined under the build key. This build definition can be used to document the recommended settings to build the image:

services:
  my-image:
    image: my-image:dev
    build:
      context: .
      dockerfile: Dockerfile
      cache_from:
      - type=registry,src=my-image:cache
      cache_to:
      - type=registry,dest=my-image:cache,mode=max

This can also include build arguments and labels as well as comments to explain the individual settings.

Option 1 for building

Docker Compose is able to perform the build without additional tooling:

docker compose build my-image

Depending on your version of Docker Compose, you may have to set the following environment variables:

COMPOSE_DOCKER_CLI_BUILD=1 \
DOCKER_BUILDKIT=1 \
docker compose build my-image

Option 2 for building

Docker buildx includes the bake subcommand which is able to consume a compose.yaml:

docker buildx bake -f compose.yaml my-image