Format Docker Compose YAML Files

Docker Compose YAML Formatting

Docker Compose uses YAML to define multi-container applications. The docker-compose.yml (or compose.yaml) file describes services, networks, volumes, and their relationships. Proper formatting is crucial for readability and correctness.

Docker Compose File Structure

version: "3.9"

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    depends_on:
      - api
    environment:
      - NGINX_HOST=example.com
    networks:
      - frontend

  api:
    build:
      context: ./api
      dockerfile: Dockerfile.prod
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/mydb
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks:
      - frontend
      - backend

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

volumes:
  pgdata:

networks:
  frontend:
  backend:

Common Formatting Mistakes

1. Port mapping quotes — "8080:8080" should be quoted to prevent YAML from interpreting the colon as a mapping separator
2. Environment variables — Two syntaxes exist: list format (- KEY=value) and map format (KEY: value); mixing them in the same service causes errors
3. Volume paths — Relative paths like ./data:/app/data must start with ./ or /
4. Indentation of list items — Service-level keys must all be at the same indentation level under the service name

Compose V2 vs. V1

Modern Docker Compose (V2) no longer requires the version field. The formatter should handle both legacy files with version: "3.x" and new files without it.

Multi-File Compose

Docker Compose supports overrides via multiple files (docker-compose.yml + docker-compose.override.yml). Each file should be formatted independently with consistent style.