Opscraft
Docker Compose · Lesson 2 of 10 · 4 min read

Defining services

A realistic file

name: shop

x-common-env: &common-env          # extension field + YAML anchor for reuse
  TZ: Asia/Kolkata
  LOG_LEVEL: info

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile
      target: runtime               # a multi-stage target
      args:
        APP_VERSION: ${APP_VERSION:-dev}
    image: 123456789012.dkr.ecr.ap-south-1.amazonaws.com/shop-api:${TAG:-dev}
    ports:
      - "8080:3000"                 # HOST:CONTAINER
    environment:
      <<: *common-env
      DB_HOST: db
      DB_USER: shop
      DB_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s
    restart: unless-stopped
    init: true
    read_only: true
    tmpfs: [/tmp]
    deploy:
      resources:
        limits: { cpus: "1.0", memory: 512M }
    logging:
      driver: json-file
      options: { max-size: "10m", max-file: "3" }

  migrate:
    image: 123456789012.dkr.ecr.ap-south-1.amazonaws.com/shop-api:${TAG:-dev}
    command: ["npm", "run", "migrate"]
    environment: { DB_HOST: db }
    depends_on:
      db: { condition: service_healthy }

  db:
    image: postgres:16.4
    environment:
      POSTGRES_USER: shop
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop"]
      interval: 5s
      retries: 10

  worker:
    build: ./worker
    depends_on: [api]
    profiles: [workers]

volumes:
  pgdata: {}

secrets:
  db_password:
    file: ./secrets/db_password.txt

Key service options

Enlarge diagram"8080:80"host portyour laptop: localhost:8080container portwhat the app listens on
Figure 1. Reading a ports entry: host port first, container port second. Other services on the network ignore the host port and use the container port.
Swipe sideways to see all of it, or tap to open it full screen.
Option What it does
image Image to run (and the name/tag given to a build)
build Build from a context; target, args, dockerfile, cache_from
command / entrypoint Override the image's CMD / ENTRYPOINT
ports Publish to the host. "8080:3000", "127.0.0.1:8080:3000" (localhost only), "3000" (random host port)
expose Document a port for other services; doesn't publish to the host (services on the same network can reach any listening port anyway)
environment / env_file Variables passed into the container
volumes Named volumes, bind mounts (./src:/app/src), :ro
depends_on Start order, optionally with health/completion conditions
healthcheck Overrides or adds the image's health check
restart no, always, on-failure, unless-stopped
deploy.resources CPU/memory limits and reservations (honoured by V2 locally)
user, working_dir Run as a UID, set the working directory
init Inject a tiny init as PID 1 to reap zombies and forward signals
read_only + tmpfs Read-only root filesystem with writable scratch space
secrets / configs Mount files under /run/secrets/ or a target path
profiles Only start this service when its profile is active
extra_hosts Add /etc/hosts entries, e.g. "host.docker.internal:host-gateway"
logging Log driver and rotation
labels Metadata (used by Traefik for routing, for example)
stop_grace_period Time between SIGTERM and SIGKILL on stop (default 10 s)

build and image together

With both keys, Compose builds the image and tags it with the image name — so docker compose build && docker compose push publishes to your registry. With only image, it pulls. pull_policy (always, missing, never, build) controls this explicitly.