Skip to main content

YAML basics: learn to read the files

YAML is a human-readable format used for Docker Compose, CI workflows, Homepage configuration, and many other applications. .yaml and .yml are equivalent extensions.

services:                  # A mapping key
  demo:                    # Nested mapping: 2 spaces
    image: nginx:stable-alpine
    restart: unless-stopped
    ports:                 # A list
      - "8080:80"          # Host port : container port
    environment:
      TZ: America/New_York

Rules​

  • Indent with spaces, not tabs. Consistency matters.
  • key: value is a mapping entry; - value is a list entry.
  • Quote values such as port mappings and ambiguous booleans.
  • # begins a comment outside quoted strings.
  • Secrets should be injected securely and never committed to public repositories.

Common errors​

did not find expected key: inspect indentation near the reported line.

ports is not a mapping: ensure ports: is aligned with image: under the same service.

Unresolved environment variable: check the .env file or shell environment, and avoid printing secrets in public logs.

Validate​

docker compose -f compose.yml config --quiet

This checks the Compose structure; it does not prove an image, mount, or network will work.