YAML untuk Docker Compose: Pola Konfigurasi dan Tips

Docker Compose menggunakan YAML untuk mendefinisikan aplikasi multi-kontainer. File docker-compose.yml yang terstruktur dengan baik adalah pembeda antara lingkungan pengembangan yang lancar dan berjam-jam debugging masalah kontainer. Panduan ini membahas pola-pola penting dan jebakan umum.

Struktur Dasar

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/myapp
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

Variabel Lingkungan

Inline

services:
  api:
    environment:
      NODE_ENV: production
      PORT: "3000"
      DEBUG: "false"

Dari File

services:
  api:
    env_file:
      - .env
      - .env.local  # Overrides .env values

Substitusi Variabel

Referensikan variabel lingkungan host:

services:
  api:
    image: myapp:${TAG:-latest}  # Default to "latest"
    environment:
      API_KEY: ${API_KEY}  # Required - fails if not set
      LOG_LEVEL: ${LOG_LEVEL:-info}  # Default to "info"

Jaringan

Jaringan Kustom

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
  backend:
    internal: true  # No external access

Layanan pada jaringan yang sama dapat saling berkomunikasi menggunakan nama layanan. Layanan db hanya dapat dijangkau dari api, bukan dari web.

Pemetaan Port

ports:
  - "8080:80"         # host:container
  - "443:443"
  - "127.0.0.1:3000:3000"  # Bind to localhost only
  - "3000"            # Random host port

Volume

Volume Bernama (Persisten)

services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
    driver: local

Bind Mount (Pengembangan)

services:
  api:
    volumes:
      - ./src:/app/src          # Source code
      - /app/node_modules       # Anonymous volume (prevent override)

Pola volume anonim (/app/node_modules) mencegah bind mount host menimpa dependensi yang terinstal di kontainer.

Health Check

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  api:
    depends_on:
      db:
        condition: service_healthy

Ini memastikan api hanya dimulai setelah db lolos health check — bukan hanya ketika kontainer dimulai.

Field Ekstensi (Pola DRY)

Gunakan field dengan prefiks x- bersama YAML anchor untuk mengurangi pengulangan:

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

x-env: &common-env
  TZ: UTC
  LOG_FORMAT: json

services:
  api:
    <<: *common
    build: ./api
    environment:
      <<: *common-env
      PORT: "3000"

  worker:
    <<: *common
    build: ./worker
    environment:
      <<: *common-env
      QUEUE: default

Untuk informasi lebih lanjut tentang YAML anchor, lihat panduan YAML anchor dan alias kami.

Compose Multi-Tahap

Pengembangan vs Produksi

# docker-compose.yml (base)
services:
  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://db:5432/myapp

# docker-compose.override.yml (dev - auto-loaded)
services:
  api:
    volumes:
      - ./api/src:/app/src
    environment:
      NODE_ENV: development
      DEBUG: "true"
    ports:
      - "3000:3000"
      - "9229:9229"  # Debug port

# docker-compose.prod.yml
services:
  api:
    environment:
      NODE_ENV: production
    deploy:
      replicas: 3

# Development (auto-loads override)
docker compose up

# Production
docker compose -f docker-compose.yml -f docker-compose.prod.yml up

Jebakan Umum

1. Nomor Port Tanpa Tanda Kutip

# RISKY - YAML interprets 80:80 as a base-60 number
ports:
  - 80:80

# SAFE - always quote
ports:
  - "80:80"

2. Variabel Lingkungan Boolean

# WRONG - YAML converts to boolean
environment:
  DEBUG: true  # Becomes Python True, not string "true"

# CORRECT - quote all env values
environment:
  DEBUG: "true"

3. Timing depends_on

depends_on hanya menunggu kontainer dimulai, bukan kesiapannya:

# Container starts but DB might not be ready
depends_on:
  - db

# Wait for health check
depends_on:
  db:
    condition: service_healthy

Validasi file Docker Compose Anda dengan YAML Validator kami.

FAQ

Apa perbedaan antara docker-compose.yml dan compose.yml?

Kedua nama file berfungsi. compose.yml adalah konvensi baru yang direkomendasikan oleh Docker. docker-compose.yml adalah nama lama. Docker Compose v2+ mencari keduanya, dengan preferensi compose.yml jika keduanya ada. Untuk proyek baru, gunakan compose.yml.

Haruskah saya menggunakan Docker Compose di produksi?

Docker Compose sangat baik untuk pengembangan dan deployment sederhana. Untuk produksi berskala besar, pertimbangkan Docker Swarm (menggunakan file Compose secara native) atau Kubernetes. Keuntungan Compose adalah konfigurasi pengembangan Anda langsung menginformasikan produksi, mengurangi perbedaan lingkungan.

Sumber Terkait

• YAML Validator — Validasi YAML Docker Compose
• YAML Anchor dan Alias — Pola konfigurasi DRY
• Tutorial Sintaks YAML — Dasar-dasar YAML