Docker Compose YAML Guide

Docker Compose YAML Basics

Docker Compose uses YAML to define services, networks, and volumes for multi-container applications.

Basic docker-compose.yml

# Docker Compose example
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    depends_on:
      - api

  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://db:5432/app
    depends_on:
      - db

  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret

volumes:
  postgres_data:

Key YAML Syntax in Docker Compose

Lists vs Maps

# List format for ports (short syntax)
ports:
  - "8080:80"
  - "443:443"

# Map format for ports (long syntax)
ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host

Environment Variables

# List format
environment:
  - DEBUG=true
  - API_KEY=secret123

# Map format (preferred)
environment:
  DEBUG: "true"
  API_KEY: secret123

# From .env file
env_file:
  - .env
  - .env.local

Multi-line Strings

# Literal block (preserves newlines)
command: |
  sh -c "
    echo 'Starting...'
    npm start
  "

# Folded block (joins lines)
healthcheck:
  test: >
    curl --fail http://localhost/health
    || exit 1

Convert Docker Compose YAML to JSON

Using yq

# Convert docker-compose.yml to JSON
yq -o=json docker-compose.yml > docker-compose.json

# Pretty print
yq -o=json -P docker-compose.yml

# Extract specific service
yq -o=json '.services.web' docker-compose.yml

Using Python

import yaml
import json

with open('docker-compose.yml') as f:
    compose = yaml.safe_load(f)

with open('docker-compose.json', 'w') as f:
    json.dump(compose, f, indent=2)

Same Config in JSON

{
  "services": {
    "web": {
      "image": "nginx:alpine",
      "ports": ["80:80"],
      "volumes": ["./html:/usr/share/nginx/html"],
      "depends_on": ["api"]
    },
    "api": {
      "build": "./api",
      "ports": ["3000:3000"],
      "environment": ["DATABASE_URL=postgres://db:5432/app"],
      "depends_on": ["db"]
    }
  }
}

Try it yourself: Use our free online converter to convert Docker Compose files instantly.

Common Docker Compose Patterns

YAML Anchors for Reuse

# Define anchor
x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"

services:
  web:
    <<: *common  # Merge anchor
    image: nginx

  api:
    <<: *common
    build: ./api

Extending Services

# base.yml
services:
  app:
    image: myapp
    environment:
      - NODE_ENV=development

# docker-compose.yml
services:
  app:
    extends:
      file: base.yml
      service: app
    ports:
      - "3000:3000"