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
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.