Docker Compose YAML File Explained

Your docker-compose.yml ran without a single error. The stack came up clean, every container shows running. And one service is still pulling the wrong image tag - because a duplicated key further down the file silently overwrote the first one, and YAML never said a word about it.

What a Compose File Is Actually Built From

A compose file has exactly one required top-level key: services. Everything else - networks, volumes, configs, secrets - is an optional declaration that most people reach for before they need to, because tutorials show them side by side as if they're equally mandatory. They aren't. The official services reference is explicit that services is where containers are actually defined; the rest exist to be referenced from a service, not to stand alone.

That distinction matters for debugging: if docker compose up fails with something like "service must be a mapping," the problem is almost always indentation under services, not a missing networks or volumes block. Start there before touching anything else.

The Syntax Mistakes That Don't Throw Errors

The mistakes that actually waste an evening aren't the ones Compose rejects outright - those at least point you at a line number. It's the ones that parse fine and run fine, just not the way you meant:

None of these produce a stack trace. That's the common thread - a compose file with one of these mistakes looks, to docker compose up, exactly like a correct one.

Stop Repeating Yourself: YAML Anchors and Aliases

In my homelab compose file, three services used to share almost the same environment: block - timezone, log level, a shared DB host - copy-pasted into each one. Every time I changed the timezone, I had three places to remember to update, and the duplicate-key mistake above happened to me exactly this way once, when I pasted a fourth service and left a stray leftover key behind.

YAML anchors fix this at the file level, not the Compose level - they work because Compose files are plain YAML, and a walkthrough of anchors and extensions in Compose builds on the same x- prefix convention the wider ecosystem uses for anchor-only blocks:

x-common-env: &common-env
  TZ: Europe/Berlin
  LOG_LEVEL: info

services:
  app:
    image: myapp:latest
    environment:
      <<: *common-env
      SERVICE_NAME: app

  worker:
    image: myapp-worker:latest
    environment:
      <<: *common-env
      SERVICE_NAME: worker

The x-common-env block is ignored by Compose itself - any top-level key starting with x- is - which is exactly why it's safe to use purely as an anchor target. &common-env names the block; <<: *common-env merges its keys into each service's environment:, and a key defined locally (like SERVICE_NAME) overrides the anchored value if the names collide. Change the timezone once, in one place, and both services pick it up.

Delete the version: Key

If your compose file still starts with version: "3.8", delete that line. In Compose v2 the schema is unified and versionless - the key is ignored, and recent releases print a deprecation warning rather than respecting the value at all. There's no behavior it still controls; keeping it only adds a line that looks load-bearing and isn't.

Validate Before You Deploy: docker compose config

docker compose config renders the fully resolved configuration - every anchor expanded, every ${VAR} interpolated, every short-form shortcut written out in full - without starting a single container. That resolved output is what actually gets sent to the Docker engine, which makes it the fastest way to catch a duplicate key, a bad interpolation, or a typo'd service name before up ever runs.

Run it in validate-only mode, which prints nothing on success and a real error on failure - scriptable, unlike squinting at the full rendered YAML:

docker compose config -q
echo $?   # 0 = valid, non-zero = broken, with a message explaining why

For the anchor example above, intentionally breaking it by duplicating the SERVICE_NAME key inside one service's environment: block still parses as valid YAML - but running docker compose config (without -q) shows you the merged result, and the duplicate collapses to whichever value came last, exactly as the table above describes. Reading that resolved output is how you catch it before the container ever starts with the wrong value.

A Pre-Deploy Checklist

1. Run docker compose config -q - exit code 0 means the file at least parses and resolves cleanly.
2. Run docker compose config (no -q) and scan for any value that doesn't match what you wrote in the source file - that mismatch is a duplicate key.
3. Confirm there's no version: line left at the top.
4. Confirm every environment: block in the file uses one syntax (list or map), not both.
5. Confirm port mappings and any value that could be misread as yes/no/true are quoted.

None of the three - duplicate keys, mixed env syntax, unquoted booleans - fail loudly. They fail by doing something other than what you wrote, which is a worse failure mode because nothing tells you to go look. Catching them is a habit (run config before up), not a one-time fix. Once your file validates cleanly, our guide to Docker Compose restart policies is a reasonable next stop - it covers what happens when a container does start correctly but keeps dying anyway.

FAQ

A compose file earns trust the same way any config file does: by being boring. If it only ever does exactly what the source text says, you stop needing to re-read it every time something looks off. For the broader setup this fits into, see our guide to Docker Compose for self-hosting.