Docker Compose — YAML Refresher

Docker Compose files are written in YAML (YAML Ain’t Markup Language). If you’ve worked with Docker, Kubernetes, or Ansible, you’ve seen YAML before. This page covers the YAML rules that matter most for Compose files.

---

YAML Basics

Indentation

YAML uses spaces for indentation — never tabs. Compose files typically use 2 spaces:

# ✅ Correct — 2-space indentation
services:
  web:
    image: nginx
    ports:
      - "80:80"

# ❌ Wrong — tabs will cause a parse error
services:
	web:
		image: nginx

Key-Value Pairs

Simple values use key: value syntax:

services:
  web:
    image: nginx:alpine
    container_name: my-web
    restart: always

Lists

Lists use a dash (-) prefix:

services:
  web:
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html
      - ./conf:/etc/nginx/conf.d

Maps (Dictionaries)

Maps are nested key-value pairs:

services:
  web:
    environment:
      NGINX_HOST: example.com
      NGINX_PORT: 80

Or using list syntax (both are equivalent for environment):

services:
  web:
    environment:
      - NGINX_HOST=example.com
      - NGINX_PORT=80

---

Strings in YAML

When Quotes Are Needed

Most strings don’t need quotes in YAML, but some do:

services:
  web:
    image: nginx          # No quotes needed
    container_name: web   # No quotes needed
    ports:
      - "80:80"           # ⚠️ Quotes NEEDED — colon would confuse YAML
    environment:
      VERSION: "3.0"      # ⚠️ Quotes recommended — could be parsed as float
      DEBUG: "true"        # ⚠️ Quotes recommended — could be parsed as boolean
      NAME: my-app         # No quotes needed

Rule of thumb: Quote strings that contain colons (:), special characters, or could be misinterpreted as numbers/booleans.

Multi-line Strings

services:
  web:
    # Literal block (preserves newlines)
    command: |
      sh -c "
        echo Starting &&
        nginx -g 'daemon off;'
      "

    # Folded block (joins lines)
    labels:
      description: >
        This is a long description
        that spans multiple lines
        but becomes one line.

---

Common YAML Mistakes in Compose

Mistake	Problem	Fix
Using tabs	Parse error	Use 2 spaces
Missing space after colon	Parse error	image: nginx not image:nginx
Unquoted port mapping	YAML interprets as sexagesimal	"80:80" not 80:80
Wrong indentation	Service nested under wrong parent	Align carefully
Trailing spaces	Can cause subtle issues	Trim trailing whitespace

---

YAML Comments

Comments start with #:

# This is a comment
services:
  web:
    image: nginx:alpine  # Inline comment
    ports:
      - "80:80"
    # environment:       # Commented-out section
    #   DEBUG: "true"

---

Validating YAML

Use docker compose config to validate your YAML:

docker compose config

If the YAML is valid, it outputs the resolved compose file. If not, you get an error with the line number:

yaml: line 5: did not find expected key

---

Summary

YAML Feature	Compose Example
Indentation	2 spaces (never tabs)
Key-value	image: nginx
Lists	- "80:80"
Maps	NGINX_HOST: example.com
Quoted strings	"80:80", "true", "3.0"
Comments	# This is a comment
Multi-line	command: \| for literal blocks

---

Quick Reference

Item	Detail
Indentation	2 spaces, never tabs
Port mappings	Always quote: ‘80:80’
Booleans as strings	Quote them: ‘true’
Validate YAML	docker compose config
Comments	# hash for comments
Lists	Dash prefix: - item