compose.yaml examples for services, variables, profiles, overrides, and dependency-aware startup.
Core service definitions and simple stacks.
Simple two-service stack with port publishing and environment variables.
services:
web:
image: nginx:alpine
ports:
- "8080:80"
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secretA good starting point for local dev stacks.
Build a service image from local source while also tagging it.
services:
app:
build:
context: .
dockerfile: Dockerfile
image: myapp:devCommon for local development and CI.
Runs a different default command than the image CMD.
services:
worker:
image: myapp:latest
command: ["python", "worker.py"]Useful for workers, migrations, and alternate entrypoints.
services:
app:
image: myapp:latest
entrypoint: ["./docker-entrypoint.sh"]Use carefully when you control container startup behavior.
services:
redis:
image: redis:7
container_name: local-redisUseful occasionally, though it reduces scaling flexibility.
Inject configuration into services and interpolate values.
Provide container environment values inline in YAML.
services:
api:
image: myapi:latest
environment:
NODE_ENV: development
PORT: "3000"Use strings for values that might be parsed unexpectedly.
Alternative environment syntax using `KEY=value` entries.
services:
api:
image: myapi:latest
environment:
- NODE_ENV=development
- PORT=3000Compact style for smaller service definitions.
Loads container environment variables from one or more files.
services:
api:
image: myapi:latest
env_file:
- .env
- .env.localGood for keeping service config out of the main YAML.
Uses shell-style variable interpolation inside the Compose file.
services:
api:
image: "myapi:${APP_TAG:-latest}"
ports:
- "${APP_PORT:-3000}:3000"Great for portable dev and CI environments.
Uses a specific env file when rendering the Compose project.
docker compose --env-file .env.production up -dUseful when switching between local, staging, and prod values.
Optional services and file layering patterns.
Marks a service as optional unless its profile is enabled.
services:
app:
image: myapp:latest
mailhog:
image: mailhog/mailhog
profiles: ["dev-tools"]Great for dev-only tools like Mailhog, Adminer, or Jaeger.
Starts the stack with a selected optional profile enabled.
docker compose --profile dev-tools up -dUse multiple `--profile` flags when needed.
Merges multiple Compose files in order.
docker compose -f compose.yaml -f compose.override.yaml up -dUseful for base + local override or base + CI override patterns.
Applies production overrides like replicas, image tags, and secrets.
docker compose -f compose.yaml -f compose.prod.yaml up -dKeeps local and production concerns separate.
Startup ordering and service readiness.
Starts `db` before `web` in dependency order.
services:
web:
image: myapp:latest
depends_on:
- db
db:
image: postgres:16Order alone does not guarantee the dependency is ready for traffic.
Defines a readiness-style health check for the service.
services:
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5Useful for observability and dependency-aware startup.
Uses health state as the dependency condition for startup ordering.
services:
web:
image: myapp:latest
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5Helpful when an app needs a database that is actually ready.