9.2 Compose File Structure

Compose file structure refers to the overall organization of a docker-compose.yml file — its top-level keys, the nesting of service definitions beneath them, and the conventions that make the file both machine-parseable and reasonably readable by a person reviewing it.

The Three Primary Top-Level Keys

A Compose file is generally organized around services, volumes, and networks, each a top-level mapping describing a different aspect of the application.

services:
  api:
    build: .

volumes:
  app-data:

networks:
  app-net:

Indentation and Nesting Conventions

As a YAML file, Compose relies on consistent indentation to express nesting — a service's configuration keys are nested beneath that service's name, which is itself nested beneath the services key.

services:
  api:
    build: .
    ports:
      - "8080:8080"
    environment:
      - LOG_LEVEL=debug

Each additional level of indentation here reflects a deeper level of configuration specificity, from the top-level services key down to an individual environment variable.

Ordering Services for Readability

While Compose doesn't require any particular ordering of services within the file, organizing them in a logical order — perhaps reflecting their dependency relationships or architectural layering — makes the file considerably easier for a person to read and understand.

services:
  frontend:
    depends_on:
      - api
  api:
    depends_on:
      - db
  db:
    image: postgres:16

Validating the Overall Structure

Before relying on a Compose file, validating its structure confirms it's both syntactically correct and free of structural mistakes that could otherwise cause confusing runtime behavior.

docker compose config

Why Understanding Compose File Structure Matters

A clear grasp of how a Compose file is organized — its top-level keys, nesting conventions, and reasonable ordering practices — makes both writing new Compose files and reading existing ones considerably more straightforward, particularly as an application's Compose file grows to describe an increasingly complex set of services.