Lesson 10 / 25

Validating With docker compose config

Catch typos before running anything.

By · 15 years in web development

Schema validation and the resolved model

docker compose config loads every file, applies interpolation and merges, validates against the Compose schema, and prints the result. A misspelled key (for example port instead of ports) is an error rather than being silently ignored. Run it in CI and before every change; add --format json with jq to check specific values, --services, --volumes or --profiles to list parts.

A typo caught by validation, run

I ran this with Docker Compose v2.38.1 and jq in the demo "shop" project. docker compose config parses, interpolates, merges and validates the files without starting containers; the Docker daemon was not running, so nothing was started. broken.yaml uses port instead of ports; validation fails with "additional properties 'port' not allowed". The sed command only shortens the file path in the message.

docker compose -f broken.yaml config 2>&1 | sed "s|$PWD/||"

Output:

validating broken.yaml: services.web additional properties 'port' not allowed

Run config in CI

A one-line CI step (docker compose config -q) catches broken Compose files before anyone pulls them.

Quick check: What does docker compose config do?

  • Resolves, merges and validates the Compose files and prints the result
  • Starts all containers
  • Deletes volumes
  • Pushes images
Answer

Resolves, merges and validates the Compose files and prints the result — Validate before you run.