[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_34":89,"_74":90,"_38":91},"articles",{"_11":12,"_13":14,"_15":16,"_17":18,"_19":20,"_21":22,"_23":24,"_25":24,"_26":16,"_27":28},"content",[31,32,33],"pageable",{"_29":22,"_30":20},"totalElements",3,"totalPages",1,"size",10,"number",0,"first",true,"last","numberOfElements","empty",false,"page_number","page_size",{"_34":124,"_36":125,"_38":126,"_40":127,"_11":128,"_43":-5,"_44":24,"_45":28,"_46":47,"_48":129,"_50":130,"_52":53,"_54":113,"_56":113,"_57":16,"_58":59,"_60":61,"_62":113,"_63":16,"_64":55,"_66":131,"_68":132,"_70":133,"_72":134},{"_34":106,"_36":107,"_38":108,"_40":109,"_11":110,"_43":-5,"_44":24,"_45":28,"_46":47,"_48":111,"_50":112,"_52":53,"_54":55,"_56":55,"_57":16,"_58":59,"_60":61,"_62":55,"_63":16,"_64":113,"_66":114,"_68":115,"_70":116,"_72":117},{"_34":35,"_36":37,"_38":39,"_40":41,"_11":42,"_43":-5,"_44":24,"_45":28,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":55,"_57":16,"_58":59,"_60":61,"_62":55,"_63":16,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73},"id",64,"title","Compose File Deep Dive","slug","docker-part-14-compose-deep-dive","excerpt","Compose spec, profiles, extends, variable interpolation","## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| **Difficulty** | 🟡 Intermediate |\n| **Prerequisites** | Basic Docker Compose usage |\n| **Compose Version** | Compose Specification (v3.8+) |\n| **Time Investment** | 28 minutes read + 45 minutes practice |\n| **Payoff** | Write DRY, maintainable multi-environment compose files |\n\n---\n\n## 🎯 What You'll Learn\n\nAfter this article, you'll be able to:\n\n1. **Master compose syntax** including all service configuration options\n2. **Use variable interpolation** with defaults, required values, and error handling\n3. **Create DRY configurations** using YAML anchors and x-extensions\n4. **Implement profiles** for conditional service inclusion\n5. **Merge multiple compose files** for environment-specific configurations\n\n---\n\n## 🔥 Production Story: The 500-Line Compose Nightmare\n\n**The Setup**: A team maintained a `docker-compose.yml` with 500+ lines of repeated configuration. Every service had the same logging, health check, and network settings copied verbatim. Making a change meant updating 12 places.\n\n**The Problem**:\n```yaml\n# 500 lines of this pattern repeated 12 times\nservices:\n service1:\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n max-file: \"3\"\n healthcheck:\n interval: 30s\n timeout: 10s\n retries: 3\n networks:\n - backend\n # ... more repeated config\n\n service2:\n # Same 40 lines repeated...\n```\n\n**The Symptoms**:\n- Configuration drift between services\n- Fear of changing shared patterns\n- New services took hours to add\n- Bugs when one service updated, others weren't\n\n**The Solution**:\n```yaml\n# Define once, use everywhere\nx-common: &common\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n max-file: \"3\"\n networks:\n - backend\n\nx-healthcheck: &healthcheck\n healthcheck:\n interval: 30s\n timeout: 10s\n retries: 3\n\nservices:\n service1:\n <<: [*common, *healthcheck]\n image: service1:latest\n\n service2:\n <<: [*common, *healthcheck]\n image: service2:latest\n```\n\n**Result**: 500 lines → 150 lines. Single source of truth for shared configuration.\n\n---\n\n## 🧠 Mental Model: Compose File Structure\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ COMPOSE FILE ANATOMY │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ x-extensions: &name # YAML anchors for reuse │ │\n│ │ key: value │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ services: # Container definitions │ │\n│ │ app: │ │\n│ │ image: myapp │ │\n│ │ <<: *name # Merge anchor │ │\n│ │ environment: │ │\n│ │ - VAR=${VAR:-default} # Interpolation │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ networks: # Network definitions │ │\n│ │ backend: │ │\n│ │ driver: bridge │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ volumes: # Volume definitions │ │\n│ │ data: │ │\n│ │ driver: local │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ configs: # Config objects (Swarm) │ │\n│ │ secrets: # Secret objects (Swarm) │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n\nProcessing Order:\n 1. Load all compose files (base + overrides)\n 2. Merge configurations (deep merge)\n 3. Expand x-extensions and anchors\n 4. Interpolate ${VARIABLES}\n 5. Validate final configuration\n```\n\n---\n\n## 🔬 Deep Dive\n\n### 1. Service Configuration Reference\n\n**Complete Service Definition**:\n\n```yaml\nservices:\n app:\n # ─── IMAGE SPECIFICATION ───────────────────────────────────\n image: myapp:${VERSION:-latest}\n # OR build from Dockerfile\n build:\n context: ./app\n dockerfile: Dockerfile\n args:\n BUILD_ENV: production\n target: runtime\n cache_from:\n - myapp:cache\n\n # ─── CONTAINER BASICS ──────────────────────────────────────\n container_name: myapp-container # Avoid in production\n hostname: myapp\n domainname: example.com\n\n # ─── RUNTIME ───────────────────────────────────────────────\n command: [\"npm\", \"start\"] # Override CMD\n entrypoint: [\"/entrypoint.sh\"] # Override ENTRYPOINT\n working_dir: /app\n user: \"1000:1000\"\n\n # ─── ENVIRONMENT ───────────────────────────────────────────\n environment:\n - NODE_ENV=production\n - DATABASE_URL # Value from host env\n env_file:\n - .env\n - .env.production\n\n # ─── NETWORKING ────────────────────────────────────────────\n ports:\n - \"8080:8080\" # host:container\n - \"127.0.0.1:9090:9090\" # localhost only\n - \"8080\" # random host port\n expose:\n - \"3000\" # Internal only, not published\n networks:\n - frontend\n - backend\n extra_hosts:\n - \"host.docker.internal:host-gateway\"\n\n # ─── VOLUMES ───────────────────────────────────────────────\n volumes:\n - data:/app/data # Named volume\n - ./config:/app/config:ro # Bind mount read-only\n - type: tmpfs # tmpfs mount\n target: /tmp\n tmpfs:\n size: 100000000 # 100MB\n\n # ─── DEPENDENCIES ──────────────────────────────────────────\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_started\n\n # ─── HEALTH CHECK ──────────────────────────────────────────\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\n # ─── RESOURCES ─────────────────────────────────────────────\n deploy:\n resources:\n limits:\n cpus: '2'\n memory: 1G\n reservations:\n cpus: '0.5'\n memory: 256M\n\n # ─── RESTART POLICY ────────────────────────────────────────\n restart: unless-stopped\n # Options: no, always, on-failure, unless-stopped\n\n # ─── LOGGING ───────────────────────────────────────────────\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n max-file: \"3\"\n\n # ─── SECURITY ──────────────────────────────────────────────\n privileged: false\n read_only: true\n cap_drop:\n - ALL\n cap_add:\n - NET_BIND_SERVICE\n security_opt:\n - no-new-privileges:true\n\n # ─── LABELS ────────────────────────────────────────────────\n labels:\n - \"com.example.description=My App\"\n - \"traefik.enable=true\"\n```\n\n---\n\n### 2. Variable Interpolation\n\n**Basic Interpolation**:\n\n```yaml\nservices:\n app:\n # Direct substitution\n image: myapp:${VERSION}\n\n # With default value\n image: myapp:${VERSION:-latest}\n\n # With default from another variable\n image: myapp:${VERSION:-${DEFAULT_VERSION}}\n\n # Required variable (error if not set)\n image: myapp:${VERSION:?VERSION must be set}\n\n # Alternative syntax for defaults\n image: myapp:${VERSION-latest} # Only if unset\n image: myapp:${VERSION:-latest} # If unset OR empty\n```\n\n**Interpolation Syntax Reference**:\n\n| Syntax | Behavior |\n|--------|----------|\n| `${VAR}` | Value of VAR, empty if unset |\n| `${VAR:-default}` | default if VAR unset or empty |\n| `${VAR-default}` | default only if VAR unset |\n| `${VAR:?error}` | Error with message if VAR unset or empty |\n| `${VAR?error}` | Error only if VAR unset |\n| `${VAR:+replacement}` | replacement if VAR set and non-empty |\n| `${VAR+replacement}` | replacement if VAR set |\n\n**Complex Interpolation Examples**:\n\n```yaml\nservices:\n app:\n environment:\n # Conditional port\n - PORT=${PORT:-${DEFAULT_PORT:-8080}}\n\n # Required in production\n - DATABASE_URL=${DATABASE_URL:?Database URL required}\n\n # Feature flags with defaults\n - ENABLE_CACHE=${ENABLE_CACHE:-true}\n - DEBUG=${DEBUG:-false}\n\n # Derived values\n - LOG_LEVEL=${LOG_LEVEL:-${NODE_ENV:+production}${NODE_ENV:-info}}\n\n # Image varies by environment\n image: ${REGISTRY:-docker.io}/${IMAGE_NAME:-myapp}:${TAG:-latest}\n\n # Conditional replicas\n deploy:\n replicas: ${REPLICAS:-1}\n```\n\n**Using .env Files**:\n\n```bash\n# .env (default, loaded automatically)\nCOMPOSE_PROJECT_NAME=myproject\nVERSION=1.2.3\n\n# .env.local (for local development)\nDEBUG=true\nDATABASE_URL=postgres://localhost/dev\n\n# .env.production\nDEBUG=false\nDATABASE_URL=postgres://prod-db/prod\n```\n\n```yaml\n# docker-compose.yml\nservices:\n app:\n env_file:\n - .env\n - .env.${ENV:-local} # Dynamic env file selection\n```\n\n**Running with different environments**:\n\n```bash\n# Development (uses .env.local by default)\ndocker compose up\n\n# Production\nENV=production docker compose up\n\n# Or with --env-file\ndocker compose --env-file .env.production up\n```\n\n---\n\n### 3. YAML Anchors and Extensions\n\n**Basic Anchors**:\n\n```yaml\n# Define anchor\nx-logging: &logging\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n max-file: \"3\"\n\nservices:\n app:\n <<: *logging # Merge anchor\n image: myapp\n\n worker:\n <<: *logging # Reuse same config\n image: myworker\n```\n\n**Multiple Anchors**:\n\n```yaml\nx-common: &common\n restart: unless-stopped\n networks:\n - backend\n\nx-logging: &logging\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n\nx-healthcheck: &healthcheck\n healthcheck:\n interval: 30s\n timeout: 10s\n retries: 3\n\nservices:\n app:\n <<: [*common, *logging, *healthcheck] # Merge multiple\n image: myapp\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n```\n\n**Nested Anchors**:\n\n```yaml\nx-base: &base\n restart: unless-stopped\n logging:\n driver: json-file\n\nx-app: &app\n <<: *base # Inherit from base\n networks:\n - frontend\n - backend\n\nx-worker: &worker\n <<: *base\n networks:\n - backend\n\nservices:\n api:\n <<: *app\n image: api:latest\n\n web:\n <<: *app\n image: web:latest\n\n background-job:\n <<: *worker\n image: worker:latest\n```\n\n**Override Anchor Values**:\n\n```yaml\nx-common: &common\n restart: unless-stopped\n deploy:\n resources:\n limits:\n memory: 512M\n\nservices:\n small-app:\n <<: *common\n image: small:latest\n # Uses default 512M memory\n\n large-app:\n <<: *common\n image: large:latest\n deploy:\n resources:\n limits:\n memory: 2G # Override to 2G\n```\n\n---\n\n### 4. Profiles for Conditional Services\n\n**Basic Profiles**:\n\n```yaml\nservices:\n app:\n image: myapp\n # No profile = always started\n\n db:\n image: postgres\n profiles:\n - dev\n - test\n # Only starts with --profile dev or --profile test\n\n debug-tools:\n image: debug:latest\n profiles:\n - debug\n # Only starts with --profile debug\n```\n\n**Running with profiles**:\n\n```bash\n# Start only services without profiles\ndocker compose up\n\n# Start services with dev profile\ndocker compose --profile dev up\n\n# Multiple profiles\ndocker compose --profile dev --profile debug up\n\n# Set via environment\nCOMPOSE_PROFILES=dev,debug docker compose up\n```\n\n**Profile Use Cases**:\n\n```yaml\nservices:\n # Always runs\n app:\n image: myapp\n depends_on:\n db:\n condition: service_healthy\n\n # Development database (local)\n db:\n image: postgres:16\n profiles: [dev]\n volumes:\n - pgdata:/var/lib/postgresql/data\n healthcheck:\n test: pg_isready -U postgres\n\n # Production uses external DB, needs migration\n db-migrate:\n image: myapp-migrate\n profiles: [prod]\n environment:\n DATABASE_URL: ${DATABASE_URL}\n\n # Debug utilities\n pgadmin:\n image: dpage/pgadmin4\n profiles: [debug]\n ports:\n - \"5050:80\"\n\n # Testing\n test-runner:\n image: myapp-test\n profiles: [test]\n depends_on:\n - db\n```\n\n**Profiles with Dependencies**:\n\n```yaml\nservices:\n app:\n image: myapp\n depends_on:\n - db # This creates implicit dependency\n\n db:\n image: postgres\n profiles: [dev]\n\n# Running \"docker compose up app\" will fail\n# because db isn't started without --profile dev\n\n# Solution: Make dependency conditional\nservices:\n app:\n image: myapp\n # No depends_on, handle connection retry in app\n```\n\n---\n\n### 5. Multi-File Compose\n\n**File Override Order**:\n\n```bash\n# Default files loaded (in order):\n# 1. docker-compose.yml (or compose.yml)\n# 2. docker-compose.override.yml (or compose.override.yml)\n\n# Custom files\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up\n\n# Or set via environment\nCOMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml docker compose up\n```\n\n**Base Configuration**:\n\n```yaml\n# docker-compose.yml (base)\nservices:\n app:\n image: myapp:${VERSION:-latest}\n environment:\n - NODE_ENV=${NODE_ENV:-development}\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n\n db:\n image: postgres:16\n environment:\n POSTGRES_PASSWORD: ${DB_PASSWORD}\n volumes:\n - pgdata:/var/lib/postgresql/data\n\nvolumes:\n pgdata:\n\nnetworks:\n default:\n name: ${COMPOSE_PROJECT_NAME:-myapp}_network\n```\n\n**Development Override**:\n\n```yaml\n# docker-compose.override.yml (auto-loaded in dev)\nservices:\n app:\n build:\n context: .\n target: development\n volumes:\n - .:/app\n - /app/node_modules\n environment:\n - DEBUG=true\n ports:\n - \"8080:8080\"\n - \"9229:9229\" # Debug port\n\n db:\n ports:\n - \"5432:5432\" # Expose for local tools\n```\n\n**Production Override**:\n\n```yaml\n# docker-compose.prod.yml\nservices:\n app:\n image: myregistry.com/myapp:${VERSION}\n deploy:\n replicas: 3\n resources:\n limits:\n memory: 1G\n environment:\n - DEBUG=false\n logging:\n driver: awslogs\n options:\n awslogs-group: myapp\n\n db:\n # Don't expose port\n ports: []\n deploy:\n resources:\n limits:\n memory: 2G\n```\n\n**Merge Behavior**:\n\n```yaml\n# Base\nservices:\n app:\n environment:\n - VAR1=base\n - VAR2=base\n volumes:\n - vol1:/data1\n\n# Override\nservices:\n app:\n environment:\n - VAR2=override # Replaces VAR2\n - VAR3=new # Adds VAR3\n volumes:\n - vol2:/data2 # Adds volume\n\n# Result\nservices:\n app:\n environment:\n - VAR1=base # Kept from base\n - VAR2=override # Overridden\n - VAR3=new # Added\n volumes:\n - vol1:/data1 # Kept\n - vol2:/data2 # Added\n```\n\n---\n\n### 6. Networks Configuration\n\n**Network Types**:\n\n```yaml\nnetworks:\n # Default bridge network\n frontend:\n driver: bridge\n\n # Custom subnet\n backend:\n driver: bridge\n ipam:\n config:\n - subnet: 172.28.0.0/16\n gateway: 172.28.0.1\n\n # External network (pre-existing)\n external-net:\n external: true\n name: my-external-network\n\n # Host network (no isolation)\n host-net:\n driver: host\n```\n\n**Service Network Configuration**:\n\n```yaml\nservices:\n app:\n networks:\n frontend:\n aliases:\n - api\n - api.local\n backend:\n ipv4_address: 172.28.0.10\n\n db:\n networks:\n backend:\n ipv4_address: 172.28.0.20\n aliases:\n - database\n - postgres\n```\n\n**Network Isolation Example**:\n\n```yaml\n# Web can reach app, app can reach db, web cannot reach db\nservices:\n web:\n networks:\n - frontend\n\n app:\n networks:\n - frontend\n - backend\n\n db:\n networks:\n - backend\n\nnetworks:\n frontend:\n backend:\n```\n\n---\n\n### 7. Volumes Configuration\n\n**Volume Types**:\n\n```yaml\nvolumes:\n # Named volume (Docker-managed)\n app-data:\n driver: local\n\n # Named volume with options\n db-data:\n driver: local\n driver_opts:\n type: none\n device: /data/postgres\n o: bind\n\n # External volume (pre-existing)\n shared-data:\n external: true\n name: my-shared-volume\n```\n\n**Service Volume Configuration**:\n\n```yaml\nservices:\n app:\n volumes:\n # Named volume\n - app-data:/app/data\n\n # Bind mount (short syntax)\n - ./config:/app/config:ro\n\n # Bind mount (long syntax)\n - type: bind\n source: ./logs\n target: /app/logs\n read_only: false\n\n # tmpfs\n - type: tmpfs\n target: /tmp\n tmpfs:\n size: 100000000\n mode: 1777\n\n # Anonymous volume\n - /app/cache\n```\n\n---\n\n### 8. Complete Production-Ready Example\n\n```yaml\n# docker-compose.yml\n\n# ═══════════════════════════════════════════════════════════════\n# EXTENSIONS (Reusable Configuration)\n# ═══════════════════════════════════════════════════════════════\n\nx-common: &common\n restart: unless-stopped\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n max-file: \"3\"\n security_opt:\n - no-new-privileges:true\n\nx-healthcheck-http: &healthcheck-http\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:${PORT:-8080}/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\nx-healthcheck-pg: &healthcheck-pg\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U ${POSTGRES_USER:-postgres}\"]\n interval: 10s\n timeout: 5s\n retries: 5\n\n# ═══════════════════════════════════════════════════════════════\n# SERVICES\n# ═══════════════════════════════════════════════════════════════\n\nservices:\n # ─── API SERVICE ─────────────────────────────────────────────\n api:\n <<: [*common, *healthcheck-http]\n image: ${REGISTRY:-docker.io}/${API_IMAGE:-myapi}:${VERSION:-latest}\n build:\n context: ./api\n target: ${BUILD_TARGET:-production}\n args:\n NODE_ENV: ${NODE_ENV:-production}\n environment:\n - NODE_ENV=${NODE_ENV:-production}\n - PORT=${API_PORT:-8080}\n - DATABASE_URL=${DATABASE_URL:?DATABASE_URL is required}\n - REDIS_URL=redis://redis:6379\n - LOG_LEVEL=${LOG_LEVEL:-info}\n ports:\n - \"${API_PORT:-8080}:${API_PORT:-8080}\"\n networks:\n - frontend\n - backend\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_started\n deploy:\n resources:\n limits:\n cpus: '${API_CPU_LIMIT:-2}'\n memory: ${API_MEMORY_LIMIT:-1G}\n reservations:\n memory: ${API_MEMORY_RESERVATION:-256M}\n\n # ─── WORKER SERVICE ──────────────────────────────────────────\n worker:\n <<: *common\n image: ${REGISTRY:-docker.io}/${WORKER_IMAGE:-myworker}:${VERSION:-latest}\n build:\n context: ./worker\n target: ${BUILD_TARGET:-production}\n environment:\n - NODE_ENV=${NODE_ENV:-production}\n - DATABASE_URL=${DATABASE_URL:?DATABASE_URL is required}\n - REDIS_URL=redis://redis:6379\n - CONCURRENCY=${WORKER_CONCURRENCY:-5}\n networks:\n - backend\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_started\n deploy:\n resources:\n limits:\n memory: ${WORKER_MEMORY_LIMIT:-512M}\n\n # ─── DATABASE ────────────────────────────────────────────────\n db:\n <<: [*common, *healthcheck-pg]\n image: postgres:${POSTGRES_VERSION:-16}-alpine\n environment:\n POSTGRES_USER: ${POSTGRES_USER:-app}\n POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD required}\n POSTGRES_DB: ${POSTGRES_DB:-app}\n volumes:\n - pgdata:/var/lib/postgresql/data\n - ./init-scripts:/docker-entrypoint-initdb.d:ro\n networks:\n - backend\n profiles:\n - dev\n - test\n deploy:\n resources:\n limits:\n memory: ${DB_MEMORY_LIMIT:-1G}\n\n # ─── REDIS ───────────────────────────────────────────────────\n redis:\n <<: *common\n image: redis:${REDIS_VERSION:-7}-alpine\n command: redis-server --appendonly yes --maxmemory ${REDIS_MAXMEMORY:-100mb}\n volumes:\n - redisdata:/data\n networks:\n - backend\n healthcheck:\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n interval: 10s\n timeout: 5s\n retries: 5\n deploy:\n resources:\n limits:\n memory: ${REDIS_MEMORY_LIMIT:-256M}\n\n # ─── DEBUG TOOLS ─────────────────────────────────────────────\n pgadmin:\n image: dpage/pgadmin4:latest\n environment:\n PGADMIN_DEFAULT_EMAIL: ${PGADMIN_EMAIL:-admin@example.com}\n PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_PASSWORD:-admin}\n ports:\n - \"${PGADMIN_PORT:-5050}:80\"\n networks:\n - backend\n profiles:\n - debug\n depends_on:\n - db\n\n redis-commander:\n image: rediscommander/redis-commander:latest\n environment:\n REDIS_HOSTS: local:redis:6379\n ports:\n - \"${REDIS_COMMANDER_PORT:-8081}:8081\"\n networks:\n - backend\n profiles:\n - debug\n depends_on:\n - redis\n\n# ═══════════════════════════════════════════════════════════════\n# NETWORKS\n# ═══════════════════════════════════════════════════════════════\n\nnetworks:\n frontend:\n driver: bridge\n backend:\n driver: bridge\n internal: true # No external access\n\n# ═══════════════════════════════════════════════════════════════\n# VOLUMES\n# ═══════════════════════════════════════════════════════════════\n\nvolumes:\n pgdata:\n driver: local\n redisdata:\n driver: local\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Hardcoded Values\n\n```yaml\n# ❌ Wrong: Hardcoded everywhere\nservices:\n app:\n image: myapp:1.2.3\n environment:\n - DATABASE_URL=postgres://user:password@db:5432/prod\n - API_KEY=sk-abc123\n\n# ✅ Right: Use interpolation\nservices:\n app:\n image: myapp:${VERSION:-latest}\n environment:\n - DATABASE_URL=${DATABASE_URL:?Required}\n - API_KEY=${API_KEY:?Required}\n```\n\n### Mistake 2: Duplicated Configuration\n\n```yaml\n# ❌ Wrong: Copy-paste everywhere\nservices:\n app1:\n logging:\n driver: json-file\n options: {max-size: \"10m\"}\n restart: unless-stopped\n app2:\n logging:\n driver: json-file\n options: {max-size: \"10m\"}\n restart: unless-stopped\n\n# ✅ Right: Use anchors\nx-common: &common\n logging:\n driver: json-file\n options: {max-size: \"10m\"}\n restart: unless-stopped\n\nservices:\n app1:\n <<: *common\n image: app1\n app2:\n <<: *common\n image: app2\n```\n\n### Mistake 3: Wrong Dependency Type\n\n```yaml\n# ❌ Wrong: depends_on without condition waits for start, not ready\nservices:\n app:\n depends_on:\n - db # Doesn't wait for DB to be ready!\n\n# ✅ Right: Use condition with health check\nservices:\n app:\n depends_on:\n db:\n condition: service_healthy\n db:\n healthcheck:\n test: pg_isready\n```\n\n### Mistake 4: Port Exposure in Production\n\n```yaml\n# ❌ Wrong: Exposing everything\nservices:\n db:\n ports:\n - \"5432:5432\" # World-accessible DB!\n\n# ✅ Right: Internal only in production\nservices:\n db:\n expose:\n - \"5432\" # Container network only\n # Or bind to localhost for development\n ports:\n - \"127.0.0.1:5432:5432\"\n```\n\n### Mistake 5: Missing Required Variables\n\n```yaml\n# ❌ Wrong: Silent failures with empty values\nservices:\n app:\n environment:\n - DATABASE_URL=${DATABASE_URL} # Empty if unset!\n\n# ✅ Right: Fail fast with clear error\nservices:\n app:\n environment:\n - DATABASE_URL=${DATABASE_URL:?DATABASE_URL must be set}\n```\n\n---\n\n## 🐛 Debug This\n\nYour compose file isn't working as expected:\n\n```yaml\nx-common: &common\n restart: unless-stopped\n networks:\n - backend\n\nservices:\n api:\n <<: *common\n image: api:latest\n ports:\n - \"8080:8080\"\n environment:\n - DB_HOST=db\n depends_on:\n - db\n\n db:\n <<: *common\n image: postgres:16\n environment:\n - POSTGRES_PASSWORD=secret\n```\n\n```bash\n$ docker compose up\napi-1 | Error: Connection refused to db:5432\n```\n\nThe API starts but can't connect to the database. What's wrong?\n\n

Click to reveal analysis

\n\n**Problems identified**:\n\n1. **No health check on db** - `depends_on` without condition just waits for container start, not database ready:\n```yaml\ndepends_on:\n - db # Only waits for container to start\n```\n\n2. **No health check defined** - Postgres needs time to initialize:\n```yaml\ndb:\n healthcheck: # Missing!\n```\n\n**Fixed version**:\n```yaml\nx-common: &common\n restart: unless-stopped\n networks:\n - backend\n\nx-healthcheck-pg: &healthcheck-pg\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U postgres\"]\n interval: 5s\n timeout: 5s\n retries: 5\n\nservices:\n api:\n <<: *common\n image: api:latest\n ports:\n - \"8080:8080\"\n environment:\n - DB_HOST=db\n depends_on:\n db:\n condition: service_healthy # Wait for healthy\n\n db:\n <<: [*common, *healthcheck-pg]\n image: postgres:16\n environment:\n - POSTGRES_PASSWORD=secret\n```\n\nThe key fix is adding `condition: service_healthy` and defining a health check for the database.\n

\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Variable Interpolation\nCreate a compose file that:\n- Uses `${VERSION}` with default `latest`\n- Requires `${DATABASE_URL}` (error if missing)\n- Uses `${PORT:-8080}` with fallback\n- Has image: `${REGISTRY:-docker.io}/${IMAGE_NAME}:${VERSION:-latest}`\n\n### Exercise 2: DRY Configuration\nRefactor this duplicated config using anchors:\n```yaml\nservices:\n api:\n restart: unless-stopped\n logging: {driver: json-file, options: {max-size: \"10m\"}}\n networks: [backend]\n worker:\n restart: unless-stopped\n logging: {driver: json-file, options: {max-size: \"10m\"}}\n networks: [backend]\n scheduler:\n restart: unless-stopped\n logging: {driver: json-file, options: {max-size: \"10m\"}}\n networks: [backend]\n```\n\n### Exercise 3: Multi-Environment Setup\nCreate:\n- `docker-compose.yml` (base configuration)\n- `docker-compose.override.yml` (development with debug port, hot reload)\n- `docker-compose.prod.yml` (production with resource limits)\n\n### Exercise 4: Profile-Based Services\nCreate a compose file with:\n- `app` service (always runs)\n- `db` service (only with `dev` profile)\n- `test-runner` service (only with `test` profile)\n- `debug-tools` service (only with `debug` profile)\n\n### Exercise 5: Network Isolation\nCreate a compose file where:\n- `web` can only reach `api`\n- `api` can reach both `web` and `db`\n- `db` can only be reached by `api`\n- Use multiple networks to achieve isolation\n\n---\n\n## 🎤 Interview Questions\n\n### Q1: What's the difference between `${VAR:-default}` and `${VAR-default}`?\n\n**Answer**: The colon (`:`) changes how empty strings are handled:\n\n| Syntax | VAR unset | VAR empty (`VAR=\"\"`) | VAR set (`VAR=\"value\"`) |\n|--------|-----------|---------------------|------------------------|\n| `${VAR:-default}` | `default` | `default` | `value` |\n| `${VAR-default}` | `default` | `` (empty) | `value` |\n\n```bash\n# Example\nunset VAR\necho \"${VAR:-default}\" # \"default\"\necho \"${VAR-default}\" # \"default\"\n\nVAR=\"\"\necho \"${VAR:-default}\" # \"default\" (treats empty as unset)\necho \"${VAR-default}\" # \"\" (empty is a valid value)\n\nVAR=\"custom\"\necho \"${VAR:-default}\" # \"custom\"\necho \"${VAR-default}\" # \"custom\"\n```\n\nUse `:-` (with colon) for most cases since empty strings usually indicate \"not configured.\"\nUse `-` (without colon) when empty string is a valid, intentional value.\n\n---\n\n### Q2: How does compose file merging work with multiple `-f` flags?\n\n**Answer**: Compose performs a deep merge with later files taking precedence:\n\n```bash\ndocker compose -f base.yml -f override.yml up\n```\n\n**Merge rules**:\n1. **Scalar values** (strings, numbers): Override completely\n2. **Arrays** (environment, volumes): Append to base\n3. **Maps** (deploy.resources): Deep merge\n\n```yaml\n# base.yml\nservices:\n app:\n image: app:v1\n environment:\n - VAR1=base\n deploy:\n resources:\n limits:\n memory: 512M\n\n# override.yml\nservices:\n app:\n image: app:v2 # Replaces (scalar)\n environment:\n - VAR2=override # Appends (array)\n deploy:\n resources:\n limits:\n cpus: '2' # Merges (map)\n\n# Result\nservices:\n app:\n image: app:v2 # From override\n environment:\n - VAR1=base # Kept from base\n - VAR2=override # Added from override\n deploy:\n resources:\n limits:\n memory: 512M # Kept from base\n cpus: '2' # Added from override\n```\n\n---\n\n### Q3: Explain `depends_on` conditions and when to use each.\n\n**Answer**: Three conditions control service startup ordering:\n\n```yaml\ndepends_on:\n service_name:\n condition: service_started | service_healthy | service_completed_successfully\n```\n\n| Condition | Waits until | Use case |\n|-----------|-------------|----------|\n| `service_started` | Container starts | Quick start, retry logic in app |\n| `service_healthy` | Health check passes | Database, cache that need init time |\n| `service_completed_successfully` | Container exits 0 | Migrations, setup scripts |\n\n```yaml\nservices:\n migrate:\n image: myapp:migrate\n command: npm run migrate\n\n api:\n depends_on:\n db:\n condition: service_healthy # DB ready\n migrate:\n condition: service_completed_successfully # Migrations done\n\n db:\n healthcheck:\n test: pg_isready\n```\n\n**Important**: Without explicit condition, `depends_on` only waits for `service_started`, which is usually insufficient for databases.\n\n---\n\n### Q4: How do YAML anchors and x-extensions differ, and when should you use each?\n\n**Answer**:\n\n**YAML Anchors** (`&name` / `*name`):\n- Pure YAML feature, works anywhere\n- Define with `&name`, reference with `*name`, merge with `<<: *name`\n- Processed by YAML parser before compose sees the file\n\n**x-extensions** (`x-*`):\n- Compose-specific feature\n- Any key starting with `x-` is ignored by compose\n- Used to store reusable content for anchors\n\n```yaml\n# x-extension as anchor storage (recommended pattern)\nx-logging: &logging\n logging:\n driver: json-file\n\n# Without x- prefix, compose would try to interpret it\n# as a top-level key and might error\n\nservices:\n app:\n <<: *logging\n```\n\n**When to use**:\n- **x-extensions**: Store reusable service configurations, options blocks\n- **Anchors**: Can be used inline anywhere in YAML\n\n```yaml\nx-common: &common # x-extension stores full config block\n restart: unless-stopped\n\nservices:\n app:\n <<: *common\n ports: &app-ports # Inline anchor for specific values\n - \"8080:8080\"\n\n app-replica:\n <<: *common\n ports: *app-ports # Reuse port config\n```\n\n---\n\n### Q5: How would you structure compose files for a project with dev, staging, and production environments?\n\n**Answer**: Use layered compose files with environment-specific overrides:\n\n```\nproject/\n├── docker-compose.yml # Base (shared) config\n├── docker-compose.override.yml # Local dev (auto-loaded)\n├── docker-compose.staging.yml # Staging overrides\n├── docker-compose.prod.yml # Production overrides\n├── .env # Default env vars\n├── .env.staging # Staging env vars\n└── .env.production # Production env vars\n```\n\n**Base** (`docker-compose.yml`):\n```yaml\nservices:\n app:\n image: ${IMAGE}:${VERSION}\n environment:\n - DATABASE_URL=${DATABASE_URL}\n healthcheck:\n test: curl -f http://localhost:8080/health\n```\n\n**Dev Override** (`docker-compose.override.yml`):\n```yaml\nservices:\n app:\n build: .\n volumes:\n - .:/app\n ports:\n - \"8080:8080\"\n - \"9229:9229\"\n db:\n image: postgres:16\n ports:\n - \"5432:5432\"\n```\n\n**Production** (`docker-compose.prod.yml`):\n```yaml\nservices:\n app:\n deploy:\n replicas: 3\n resources:\n limits:\n memory: 1G\n logging:\n driver: awslogs\n db: # Don't use compose db in prod\n profiles: [never]\n```\n\n**Usage**:\n```bash\n# Development (auto-loads override)\ndocker compose up\n\n# Staging\ndocker compose -f docker-compose.yml -f docker-compose.staging.yml \\\n --env-file .env.staging up\n\n# Production\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml \\\n --env-file .env.production up\n```\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### Compose File Structure\n- **x-extensions**: Reusable configuration blocks\n- **services**: Container definitions\n- **networks**: Network topology\n- **volumes**: Persistent storage\n- **configs/secrets**: Sensitive data (Swarm)\n\n### Variable Interpolation\n| Syntax | Behavior |\n|--------|----------|\n| `${VAR:-default}` | Default if unset or empty |\n| `${VAR:?error}` | Required, error if missing |\n| `${VAR:+value}` | Value if VAR is set |\n\n### DRY Configuration\n```yaml\nx-common: &common\n restart: unless-stopped\n\nservices:\n app:\n <<: *common\n```\n\n### Profiles\n```bash\ndocker compose --profile dev up\n```\n\n### Multi-File\n```bash\ndocker compose -f base.yml -f override.yml up\n```\n\n---\n\n## 📋 Quick Reference\n\n```yaml\n# Variable with default\nimage: app:${VERSION:-latest}\n\n# Required variable\nenvironment:\n - KEY=${KEY:?Required}\n\n# Anchor definition and usage\nx-logging: &logging\n logging: {driver: json-file}\n\nservices:\n app:\n <<: *logging\n\n# Health-based dependency\ndepends_on:\n db:\n condition: service_healthy\n\n# Profile\nprofiles: [dev]\n\n# Resource limits\ndeploy:\n resources:\n limits:\n memory: 1G\n```\n\n---\n\n## 📅 Review Schedule\n\n- **Day 1**: Practice variable interpolation\n- **Day 3**: Refactor existing compose with anchors\n- **Day 7**: Set up multi-environment project\n- **Day 14**: Implement profiles for optional services\n- **Day 30**: Review and optimize production compose files\n\n---\n\n## 📚 Series Navigation\n\n- **Previous**: [Part 13 - Debugging Containers](/articles/docker-part-13-debugging)\n- **Next**: [Part 15 - Service Dependencies & Orchestration](/articles/docker-part-15-dependencies)\n- **Index**: [Docker Compendium Series](/series/docker-compendium)","featuredImage","isPublished","isFeatured","subscriptionType","BASIC","publishedAt","2026-06-10T07:19:25.524781Z","createdAt","2026-06-10T07:19:25.525428Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes",16,"estimatedReadingTime","authorId","authorUsername","tomasz_main","categoryName","Devops","readingTime","seriesId","seriesOrder",14,"author",{"_34":16,"_96":59,"_97":98,"_99":100,"_101":-5,"_102":-5,"_103":-5,"_104":-5,"_105":-5},"category",{"_34":92,"_74":61,"_38":93,"_77":94,"_95":-5},"tags",[80,81,82],"series",{"_34":16,"_74":75,"_38":76,"_77":78,"_79":24},"name","Docker Compendium: From Practitioner to Expert","docker-compendium","description","Master Docker internals, optimization patterns, and production best practices. For developers who use Docker daily but want deeper understanding of what's happening under the hood. Not a beginner series - we assume you can write Dockerfiles and use docker-compose. Learn what namespaces and cgroups really do, why your builds are slow, how to debug containers that crash, and how to run Docker in production like a pro.\n","isActive",{"_34":89,"_74":90,"_38":91},{"_34":86,"_74":87,"_38":88},{"_34":83,"_74":84,"_38":85},213,"Docker","docker",109,"Configuration","configuration",242,"Compose","compose",7,"devops","Category for Devops","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl",65,"Service Dependencies & Orchestration","docker-part-15-dependencies","depends_on, healthchecks, restart policies","## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| **Difficulty** | 🟡 Intermediate |\n| **Prerequisites** | Part 14 (Compose Deep Dive) |\n| **Key Concepts** | depends_on, health checks, startup ordering, graceful shutdown |\n| **Time Investment** | 26 minutes read + 45 minutes practice |\n| **Payoff** | Zero-downtime deployments and reliable service orchestration |\n\n---\n\n## 🎯 What You'll Learn\n\nAfter this article, you'll be able to:\n\n1. **Implement proper startup ordering** with health-based dependencies\n2. **Design health checks** that accurately reflect service readiness\n3. **Handle graceful shutdown** to prevent request loss during deployments\n4. **Manage service initialization** including migrations and seeding\n5. **Debug dependency issues** and circular dependency problems\n\n---\n\n## 🔥 Production Story: The Race Condition Deployment\n\n**The Setup**: A microservices application with API, worker, and database. Every deployment, about 10% of initial requests failed with \"Connection refused.\"\n\n**The Configuration**:\n```yaml\nservices:\n api:\n depends_on:\n - db\n - redis\n # ...\n\n worker:\n depends_on:\n - db\n - redis\n # ...\n```\n\n**The Investigation**:\n```bash\n# API logs on startup\nConnecting to database...\nError: Connection refused to db:5432\nRetrying in 1s...\nConnecting to database...\nConnected!\nServer listening on port 8080\n```\n\n**Root Cause**: `depends_on` only waits for container start, not database readiness. PostgreSQL takes 2-5 seconds to initialize. API started connecting before Postgres was ready.\n\n**The Fix**:\n```yaml\nservices:\n api:\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_healthy\n\n db:\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U postgres\"]\n interval: 5s\n timeout: 5s\n retries: 5\n start_period: 10s\n\n redis:\n healthcheck:\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n interval: 5s\n timeout: 3s\n retries: 5\n```\n\n**Result**: Zero failed connections during deployment. API waits for databases to be fully ready before starting.\n\n---\n\n## 🧠 Mental Model: Service Lifecycle\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ SERVICE LIFECYCLE │\n├──────────────────────────────────────────────────────────────────┤\n│ │\n│ STARTUP PHASE │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ │ │\n│ │ [Created] ──→ [Starting] ──→ [Running] ──→ [Healthy] │ │\n│ │ │ │ │ │ │ │\n│ │ │ start_period healthcheck ready │ │\n│ │ │ (grace time) begins to serve │ │\n│ │ │ │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ DEPENDENCY ORDERING │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ │ │\n│ │ Infrastructure ──→ Core Services ──→ App │ │\n│ │ (db, redis) (migrations) (api) │ │\n│ │ │ │\n│ │ service_healthy service_completed service_healthy│ │\n│ │ _successfully │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ SHUTDOWN PHASE │\n│ ┌────────────────────────────────────────────────────────┐ │\n│ │ │ │\n│ │ [Running] ──→ [SIGTERM] ──→ [Draining] ──→ [Stopped] │ │\n│ │ │ │ │ │ │\n│ │ stop_signal stop_grace SIGKILL │ │\n│ │ received _period if needed │ │\n│ │ │ │\n│ └────────────────────────────────────────────────────────┘ │\n│ │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 🔬 Deep Dive\n\n### 1. Understanding depends_on Conditions\n\n**The Three Conditions**:\n\n```yaml\nservices:\n app:\n depends_on:\n # Condition 1: Just wait for container to start\n service1:\n condition: service_started\n\n # Condition 2: Wait for health check to pass\n service2:\n condition: service_healthy\n\n # Condition 3: Wait for container to exit with code 0\n service3:\n condition: service_completed_successfully\n```\n\n**When to Use Each**:\n\n| Condition | Use Case | Example |\n|-----------|----------|---------|\n| `service_started` | Quick-start services, app handles retry | Feature flags service |\n| `service_healthy` | Must be ready before dependent starts | Database, cache, queue |\n| `service_completed_successfully` | One-time setup tasks | Migrations, seed data |\n\n**Complete Dependency Example**:\n\n```yaml\nservices:\n # Infrastructure layer\n db:\n image: postgres:16\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U postgres\"]\n interval: 5s\n timeout: 5s\n retries: 5\n start_period: 10s\n\n redis:\n image: redis:7\n healthcheck:\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n interval: 5s\n timeout: 3s\n retries: 5\n\n # Setup layer - runs once\n migrate:\n image: myapp:latest\n command: npm run migrate\n depends_on:\n db:\n condition: service_healthy\n\n seed:\n image: myapp:latest\n command: npm run seed\n depends_on:\n migrate:\n condition: service_completed_successfully\n\n # Application layer\n api:\n image: myapp:latest\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_healthy\n seed:\n condition: service_completed_successfully\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n interval: 10s\n timeout: 5s\n retries: 3\n start_period: 30s\n\n # Worker layer\n worker:\n image: myapp:latest\n command: npm run worker\n depends_on:\n api:\n condition: service_healthy # Wait for API to be ready\n```\n\n---\n\n### 2. Designing Effective Health Checks\n\n**Health Check Components**:\n\n```yaml\nhealthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n interval: 30s # How often to check\n timeout: 10s # Max time for check to complete\n retries: 3 # Failures before unhealthy\n start_period: 40s # Grace period for slow starts\n```\n\n**Database Health Checks**:\n\n```yaml\n# PostgreSQL\nhealthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-postgres}\"]\n interval: 5s\n timeout: 5s\n retries: 5\n\n# MySQL\nhealthcheck:\n test: [\"CMD\", \"mysqladmin\", \"ping\", \"-h\", \"localhost\", \"-u\", \"root\", \"-p${MYSQL_ROOT_PASSWORD}\"]\n interval: 5s\n timeout: 5s\n retries: 5\n\n# MongoDB\nhealthcheck:\n test: [\"CMD\", \"mongosh\", \"--eval\", \"db.adminCommand('ping')\"]\n interval: 10s\n timeout: 5s\n retries: 5\n```\n\n**Cache/Queue Health Checks**:\n\n```yaml\n# Redis\nhealthcheck:\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n interval: 5s\n timeout: 3s\n retries: 5\n\n# Redis with AUTH\nhealthcheck:\n test: [\"CMD-SHELL\", \"redis-cli -a ${REDIS_PASSWORD} ping | grep PONG\"]\n interval: 5s\n timeout: 3s\n retries: 5\n\n# RabbitMQ\nhealthcheck:\n test: [\"CMD\", \"rabbitmq-diagnostics\", \"-q\", \"ping\"]\n interval: 10s\n timeout: 10s\n retries: 3\n\n# Kafka (via kafka-topics)\nhealthcheck:\n test: [\"CMD-SHELL\", \"kafka-topics.sh --bootstrap-server localhost:9092 --list\"]\n interval: 10s\n timeout: 10s\n retries: 5\n```\n\n**Application Health Checks**:\n\n```yaml\n# Basic HTTP check\nhealthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n\n# Check with specific response\nhealthcheck:\n test: [\"CMD-SHELL\", \"curl -sf http://localhost:8080/health | grep -q '\\\"status\\\":\\\"UP\\\"'\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n# HTTPS with insecure (self-signed cert)\nhealthcheck:\n test: [\"CMD\", \"curl\", \"-kf\", \"https://localhost:8443/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n\n# For images without curl\nhealthcheck:\n test: [\"CMD\", \"wget\", \"--spider\", \"-q\", \"http://localhost:8080/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n**Liveness vs Readiness** (implementing both in one endpoint):\n\n```javascript\n// Node.js health endpoint\napp.get('/health', (req, res) => {\n // Liveness: Is the process alive?\n // (If this endpoint responds, yes)\n\n // Readiness: Can we serve traffic?\n const checks = {\n database: checkDatabase(),\n redis: checkRedis(),\n disk: checkDiskSpace()\n };\n\n const allHealthy = Object.values(checks).every(c => c.status === 'UP');\n\n res.status(allHealthy ? 200 : 503).json({\n status: allHealthy ? 'UP' : 'DOWN',\n checks\n });\n});\n\n// Separate endpoints for different purposes\napp.get('/health/live', (req, res) => {\n // Just respond if process is alive\n res.json({ status: 'UP' });\n});\n\napp.get('/health/ready', (req, res) => {\n // Check all dependencies\n const ready = checkAllDependencies();\n res.status(ready ? 200 : 503).json({ ready });\n});\n```\n\n---\n\n### 3. Graceful Shutdown Patterns\n\n**Understanding Stop Signals**:\n\n```yaml\nservices:\n app:\n stop_signal: SIGTERM # Signal sent first (default)\n stop_grace_period: 30s # Time before SIGKILL\n```\n\n**Signal Handling in Application**:\n\n```javascript\n// Node.js graceful shutdown\nconst server = app.listen(8080);\n\nconst gracefulShutdown = async (signal) => {\n console.log(`${signal} received, shutting down gracefully`);\n\n // 1. Stop accepting new connections\n server.close(() => {\n console.log('HTTP server closed');\n });\n\n // 2. Wait for existing requests to complete\n // (server.close handles this)\n\n // 3. Close database connections\n await db.close();\n console.log('Database connections closed');\n\n // 4. Close other resources\n await redis.quit();\n console.log('Redis connection closed');\n\n process.exit(0);\n};\n\nprocess.on('SIGTERM', () => gracefulShutdown('SIGTERM'));\nprocess.on('SIGINT', () => gracefulShutdown('SIGINT'));\n```\n\n```java\n// Java Spring Boot graceful shutdown\n@Configuration\npublic class GracefulShutdownConfig {\n\n @Bean\n public GracefulShutdownHandler gracefulShutdownHandler() {\n return new GracefulShutdownHandler();\n }\n}\n\n// application.yml\nserver:\n shutdown: graceful\n\nspring:\n lifecycle:\n timeout-per-shutdown-phase: 30s\n```\n\n**Compose Configuration for Graceful Shutdown**:\n\n```yaml\nservices:\n api:\n image: myapp:latest\n stop_grace_period: 30s\n deploy:\n update_config:\n order: start-first # Start new before stopping old\n failure_action: rollback\n rollback_config:\n parallelism: 1\n```\n\n**Pre-Stop Hook Pattern** (wait for connections to drain):\n\n```yaml\nservices:\n api:\n image: myapp:latest\n # Custom entrypoint that handles shutdown\n entrypoint: [\"/bin/sh\", \"-c\"]\n command:\n - |\n # Trap SIGTERM\n trap 'echo \"SIGTERM received\"; kill -TERM $PID; wait $PID' TERM\n\n # Start app in background\n node server.js &\n PID=$!\n\n # Wait for app\n wait $PID\n```\n\n---\n\n### 4. Migration and Initialization Patterns\n\n**One-Time Migration Service**:\n\n```yaml\nservices:\n migrate:\n image: myapp:latest\n command: npm run migrate\n depends_on:\n db:\n condition: service_healthy\n # No restart - should only run once\n restart: \"no\"\n # No healthcheck needed - will exit\n```\n\n**Migration with Locking** (prevent concurrent runs):\n\n```yaml\nservices:\n migrate:\n image: myapp:latest\n command: >\n sh -c \"\n # Try to acquire lock\n if ! mkdir /tmp/migration.lock 2>/dev/null; then\n echo 'Migration already running, skipping'\n exit 0\n fi\n trap 'rmdir /tmp/migration.lock' EXIT\n npm run migrate\n \"\n volumes:\n - migration-lock:/tmp\n depends_on:\n db:\n condition: service_healthy\n\nvolumes:\n migration-lock:\n```\n\n**Seed Data Pattern**:\n\n```yaml\nservices:\n # Only seed in development\n seed:\n image: myapp:latest\n command: npm run seed\n profiles: [dev]\n depends_on:\n migrate:\n condition: service_completed_successfully\n restart: \"no\"\n```\n\n**Wait-For Pattern** (when depends_on isn't enough):\n\n```yaml\nservices:\n app:\n image: myapp:latest\n entrypoint: [\"/wait-for-it.sh\", \"db:5432\", \"--\", \"npm\", \"start\"]\n volumes:\n - ./wait-for-it.sh:/wait-for-it.sh:ro\n```\n\nOr build it into the image:\n\n```dockerfile\nFROM node:20-alpine\n\n# Add wait script\nADD https://github.com/vishnubob/wait-for-it/raw/master/wait-for-it.sh /wait-for-it.sh\nRUN chmod +x /wait-for-it.sh\n\n# Your app\nCOPY . /app\nWORKDIR /app\n\nCMD [\"/wait-for-it.sh\", \"db:5432\", \"-t\", \"60\", \"--\", \"npm\", \"start\"]\n```\n\n---\n\n### 5. Handling Circular Dependencies\n\n**Problem: Circular Dependency**:\n\n```yaml\n# ❌ This creates a circular dependency\nservices:\n service-a:\n depends_on:\n service-b:\n condition: service_healthy\n\n service-b:\n depends_on:\n service-a:\n condition: service_healthy\n# Neither can start because each waits for the other!\n```\n\n**Solution 1: Break the Cycle with service_started**:\n\n```yaml\nservices:\n service-a:\n depends_on:\n service-b:\n condition: service_started # Just start, don't wait for healthy\n healthcheck:\n test: curl -f http://localhost:8080/health\n interval: 10s\n retries: 10 # More retries to handle startup race\n\n service-b:\n depends_on:\n service-a:\n condition: service_started\n healthcheck:\n test: curl -f http://localhost:8080/health\n interval: 10s\n retries: 10\n```\n\n**Solution 2: Design Out the Circular Dependency**:\n\n```yaml\n# Instead of A <-> B, use:\n# A -> shared-resource <- B\n\nservices:\n shared-db:\n image: postgres:16\n healthcheck:\n test: pg_isready\n\n service-a:\n depends_on:\n shared-db:\n condition: service_healthy\n # Communicates with B through DB or queue\n\n service-b:\n depends_on:\n shared-db:\n condition: service_healthy\n # Communicates with A through DB or queue\n```\n\n**Solution 3: Event-Driven Communication**:\n\n```yaml\nservices:\n redis:\n image: redis:7\n healthcheck:\n test: redis-cli ping\n\n service-a:\n depends_on:\n redis:\n condition: service_healthy\n # Publishes events, subscribes to B's events\n\n service-b:\n depends_on:\n redis:\n condition: service_healthy\n # Publishes events, subscribes to A's events\n```\n\n---\n\n### 6. Startup and Shutdown Order\n\n**Startup Order** (compose figures this out from depends_on):\n\n```\n1. Infrastructure (db, redis, queue)\n2. Setup tasks (migrations, seeds)\n3. Core services (api, worker)\n4. Auxiliary services (monitoring, logging)\n```\n\n**Shutdown Order** (reverse of startup):\n\n```yaml\nservices:\n # Stops last (infrastructure)\n db:\n # ...\n\n # Stops second\n api:\n depends_on:\n - db\n\n # Stops first (depends on api)\n nginx:\n depends_on:\n - api\n```\n\n**Controlling Shutdown Order Explicitly**:\n\n```bash\n# Manual ordered shutdown\ndocker compose stop nginx # Stop reverse proxy first\ndocker compose stop api # Stop API\ndocker compose stop worker # Stop workers\ndocker compose stop db redis # Stop infrastructure last\n```\n\n**Automated Graceful Shutdown Script**:\n\n```bash\n#!/bin/bash\n# graceful-shutdown.sh\n\nset -e\n\necho \"Starting graceful shutdown...\"\n\n# 1. Stop accepting new traffic\ndocker compose stop nginx\nsleep 5 # Allow in-flight requests to complete\n\n# 2. Stop application services\ndocker compose stop api worker\nsleep 10 # Allow graceful shutdown\n\n# 3. Stop infrastructure\ndocker compose stop redis db\n\necho \"Shutdown complete\"\n```\n\n---\n\n### 7. Complete Production Example\n\n```yaml\n# docker-compose.yml\n\nx-healthcheck-defaults: &healthcheck-defaults\n interval: 10s\n timeout: 5s\n retries: 5\n start_period: 30s\n\nservices:\n # ═══════════════════════════════════════════════════════════════\n # INFRASTRUCTURE LAYER\n # ═══════════════════════════════════════════════════════════════\n\n db:\n image: postgres:16-alpine\n environment:\n POSTGRES_USER: app\n POSTGRES_PASSWORD: ${DB_PASSWORD:?Required}\n POSTGRES_DB: app\n volumes:\n - pgdata:/var/lib/postgresql/data\n healthcheck:\n <<: *healthcheck-defaults\n test: [\"CMD-SHELL\", \"pg_isready -U app -d app\"]\n start_period: 10s\n\n redis:\n image: redis:7-alpine\n command: redis-server --appendonly yes\n volumes:\n - redisdata:/data\n healthcheck:\n <<: *healthcheck-defaults\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n start_period: 5s\n\n # ═══════════════════════════════════════════════════════════════\n # SETUP LAYER (runs once on deploy)\n # ═══════════════════════════════════════════════════════════════\n\n migrate:\n image: ${IMAGE}:${VERSION}\n command: npm run migrate\n environment:\n DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app\n depends_on:\n db:\n condition: service_healthy\n restart: \"no\"\n profiles: [setup]\n\n # ═══════════════════════════════════════════════════════════════\n # APPLICATION LAYER\n # ═══════════════════════════════════════════════════════════════\n\n api:\n image: ${IMAGE}:${VERSION}\n environment:\n NODE_ENV: production\n PORT: 8080\n DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app\n REDIS_URL: redis://redis:6379\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_healthy\n healthcheck:\n <<: *healthcheck-defaults\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health/ready\"]\n stop_grace_period: 30s\n deploy:\n resources:\n limits:\n memory: 1G\n\n worker:\n image: ${IMAGE}:${VERSION}\n command: npm run worker\n environment:\n NODE_ENV: production\n DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app\n REDIS_URL: redis://redis:6379\n depends_on:\n api:\n condition: service_healthy # Start after API is ready\n healthcheck:\n <<: *healthcheck-defaults\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:9090/health\"]\n start_period: 10s\n stop_grace_period: 60s # Longer for job completion\n deploy:\n resources:\n limits:\n memory: 512M\n\n # ═══════════════════════════════════════════════════════════════\n # PROXY LAYER\n # ═══════════════════════════════════════════════════════════════\n\n nginx:\n image: nginx:alpine\n ports:\n - \"80:80\"\n - \"443:443\"\n volumes:\n - ./nginx.conf:/etc/nginx/nginx.conf:ro\n - ./certs:/etc/nginx/certs:ro\n depends_on:\n api:\n condition: service_healthy\n healthcheck:\n <<: *healthcheck-defaults\n test: [\"CMD\", \"nginx\", \"-t\"]\n start_period: 5s\n stop_grace_period: 10s\n\nvolumes:\n pgdata:\n redisdata:\n```\n\n**Deployment Script**:\n\n```bash\n#!/bin/bash\n# deploy.sh\n\nset -e\n\nexport IMAGE=myapp\nexport VERSION=${1:-latest}\nexport DB_PASSWORD=${DB_PASSWORD:?DB_PASSWORD required}\n\necho \"Deploying version: $VERSION\"\n\n# 1. Pull new images\ndocker compose pull\n\n# 2. Run migrations\necho \"Running migrations...\"\ndocker compose --profile setup run --rm migrate\n\n# 3. Rolling update of services\necho \"Updating services...\"\ndocker compose up -d --no-deps api\ndocker compose up -d --no-deps worker\ndocker compose up -d --no-deps nginx\n\n# 4. Wait for health checks\necho \"Waiting for services to be healthy...\"\ntimeout 120 bash -c '\n while ! docker compose ps | grep -q \"(healthy)\"; do\n sleep 2\n done\n'\n\n# 5. Clean up old containers\ndocker compose down --remove-orphans\n\necho \"Deployment complete!\"\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Using depends_on Without Condition\n\n```yaml\n# ❌ Wrong: Only waits for container start\nservices:\n app:\n depends_on:\n - db # DB not ready when app starts!\n\n# ✅ Right: Wait for healthy\nservices:\n app:\n depends_on:\n db:\n condition: service_healthy\n db:\n healthcheck:\n test: pg_isready\n```\n\n### Mistake 2: Shallow Health Checks\n\n```yaml\n# ❌ Wrong: Just checks if port is open\nhealthcheck:\n test: [\"CMD\", \"nc\", \"-z\", \"localhost\", \"8080\"]\n\n# ✅ Right: Checks actual functionality\nhealthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health/ready\"]\n```\n\n### Mistake 3: Missing start_period\n\n```yaml\n# ❌ Wrong: Health check fails during slow startup\nhealthcheck:\n test: curl -f http://localhost:8080/health\n interval: 10s\n retries: 3\n # Container marked unhealthy after 30s even if startup takes 60s\n\n# ✅ Right: Allow time for initialization\nhealthcheck:\n test: curl -f http://localhost:8080/health\n interval: 10s\n retries: 3\n start_period: 90s # Don't count failures during first 90s\n```\n\n### Mistake 4: Immediate SIGKILL\n\n```yaml\n# ❌ Wrong: Only 10s to shutdown\nstop_grace_period: 10s\n# Long-running requests get killed!\n\n# ✅ Right: Allow time for graceful shutdown\nstop_grace_period: 30s # Or longer for workers\n```\n\n### Mistake 5: Not Handling SIGTERM\n\n```javascript\n// ❌ Wrong: Process killed immediately\nconst server = app.listen(8080);\n// No signal handling - connections dropped on stop\n\n// ✅ Right: Graceful shutdown\nconst server = app.listen(8080);\n\nprocess.on('SIGTERM', () => {\n console.log('SIGTERM received, closing server');\n server.close(() => {\n console.log('Server closed');\n process.exit(0);\n });\n});\n```\n\n---\n\n## 🐛 Debug This\n\nServices won't start in the right order:\n\n```yaml\nservices:\n api:\n image: myapp:latest\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_healthy\n healthcheck:\n test: curl -f http://localhost:8080/health\n interval: 5s\n retries: 3\n\n db:\n image: postgres:16\n healthcheck:\n test: pg_isready\n interval: 5s\n retries: 5\n\n redis:\n image: redis:7\n healthcheck:\n test: redis-cli ping\n interval: 5s\n retries: 5\n```\n\n```bash\n$ docker compose up\ndb is healthy\nredis is healthy\napi exited with code 1\n\n$ docker compose logs api\nError: ECONNREFUSED connecting to db:5432\n```\n\nAPI fails even though db shows healthy. What's wrong?\n\n

Click to reveal analysis

\n\n**Problems identified**:\n\n1. **Missing start_period on API** - API health check starts immediately, but API needs time to boot:\n```yaml\nhealthcheck:\n test: curl -f http://localhost:8080/health\n interval: 5s\n retries: 3\n # No start_period! API marked unhealthy during startup\n```\n\n2. **Missing PostgreSQL user in health check**:\n```yaml\nhealthcheck:\n test: pg_isready # Uses default user, not app user\n```\n\n3. **API needs connection retry logic** - Even with depends_on, there's a small window where connection might fail.\n\n**Fixed version**:\n```yaml\nservices:\n api:\n image: myapp:latest\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_healthy\n healthcheck:\n test: curl -f http://localhost:8080/health\n interval: 10s\n timeout: 5s\n retries: 3\n start_period: 30s # Allow startup time\n\n db:\n image: postgres:16\n environment:\n POSTGRES_USER: app\n POSTGRES_PASSWORD: secret\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U app\"] # Check as app user\n interval: 5s\n timeout: 5s\n retries: 5\n start_period: 10s\n\n redis:\n image: redis:7\n healthcheck:\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n interval: 5s\n timeout: 3s\n retries: 5\n```\n\nAdditionally, the application should implement connection retry:\n```javascript\nconst connectWithRetry = async () => {\n for (let i = 0; i < 10; i++) {\n try {\n await db.connect();\n return;\n } catch (err) {\n console.log(`DB connection attempt ${i + 1} failed, retrying...`);\n await sleep(1000);\n }\n }\n throw new Error('Could not connect to database');\n};\n```\n

\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Basic Dependency Chain\nCreate a compose file with:\n- PostgreSQL with proper health check\n- API that depends on PostgreSQL being healthy\n- Worker that depends on API being healthy\n\n### Exercise 2: Migration Pattern\nImplement a migration service that:\n- Runs only once (doesn't restart)\n- Waits for database to be healthy\n- API waits for migration to complete\n\n### Exercise 3: Graceful Shutdown\nCreate an application that:\n- Handles SIGTERM properly\n- Completes in-flight requests before stopping\n- Has appropriate stop_grace_period\n\n### Exercise 4: Health Check Design\nDesign health checks for:\n- A service that needs 45 seconds to start\n- A service that should fail if Redis is unreachable\n- A service with both liveness and readiness requirements\n\n### Exercise 5: Circular Dependency Resolution\nYou have two services that need to communicate with each other. Design a solution that:\n- Avoids circular depends_on\n- Ensures both services can find each other\n- Handles the case where one service starts before the other\n\n---\n\n## 🎤 Interview Questions\n\n### Q1: What's the difference between `service_started` and `service_healthy` conditions?\n\n**Answer**:\n\n| Condition | Waits For | Use Case |\n|-----------|-----------|----------|\n| `service_started` | Container is running | Quick services, apps with built-in retry |\n| `service_healthy` | Health check passes | Databases, caches that need init time |\n\n```yaml\n# service_started - just waits for container\ndepends_on:\n cache:\n condition: service_started\n# Good when: app has retry logic, service starts fast\n\n# service_healthy - waits for health check\ndepends_on:\n db:\n condition: service_healthy\n# Good when: dependent can't handle connection failures\n```\n\n**Important**: Without explicit condition, `depends_on` defaults to `service_started`, which is why many deployments have race conditions - developers assume it waits for readiness.\n\n---\n\n### Q2: How would you implement a health check that verifies database connectivity?\n\n**Answer**: Two approaches - database-side and app-side:\n\n**Database-side health check**:\n```yaml\nservices:\n db:\n image: postgres:16\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}\"]\n interval: 5s\n timeout: 5s\n retries: 5\n```\n\n**Application-side health check** (more comprehensive):\n```yaml\nservices:\n api:\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health/ready\"]\n```\n\n```javascript\n// /health/ready endpoint\napp.get('/health/ready', async (req, res) => {\n try {\n // Test actual query, not just connection\n await db.query('SELECT 1');\n res.json({ database: 'connected' });\n } catch (err) {\n res.status(503).json({ database: 'disconnected', error: err.message });\n }\n});\n```\n\nBest practice is both: database health check ensures it accepts connections, application health check ensures your specific user and database work.\n\n---\n\n### Q3: How do you handle graceful shutdown in a containerized application?\n\n**Answer**: Multi-layer approach:\n\n1. **Compose configuration**:\n```yaml\nservices:\n api:\n stop_signal: SIGTERM\n stop_grace_period: 30s\n```\n\n2. **Application signal handling**:\n```javascript\nlet isShuttingDown = false;\n\nprocess.on('SIGTERM', async () => {\n isShuttingDown = true;\n console.log('Shutdown initiated');\n\n // 1. Stop accepting new requests\n server.close();\n\n // 2. Wait for in-flight requests (handled by server.close)\n\n // 3. Close database connections\n await db.end();\n\n // 4. Exit\n process.exit(0);\n});\n\n// Middleware to reject new requests during shutdown\napp.use((req, res, next) => {\n if (isShuttingDown) {\n res.status(503).json({ error: 'Server shutting down' });\n } else {\n next();\n }\n});\n```\n\n3. **Load balancer coordination**: Remove container from pool before stopping:\n```bash\n# Pre-stop script\ncurl -X DELETE http://lb/backends/this-instance\nsleep 5 # Allow in-flight to complete\nkill -TERM 1\n```\n\n---\n\n### Q4: How do you prevent race conditions when multiple services need the same database?\n\n**Answer**: Several strategies:\n\n1. **Single migration service with completion dependency**:\n```yaml\nservices:\n migrate:\n command: npm run migrate\n depends_on:\n db:\n condition: service_healthy\n restart: \"no\"\n\n api:\n depends_on:\n migrate:\n condition: service_completed_successfully\n\n worker:\n depends_on:\n migrate:\n condition: service_completed_successfully\n```\n\n2. **Database-level migration locking**:\n```javascript\n// Migration script with advisory lock\nasync function migrate() {\n // Acquire lock (only one process can hold it)\n await db.query('SELECT pg_advisory_lock(12345)');\n\n try {\n await runMigrations();\n } finally {\n await db.query('SELECT pg_advisory_unlock(12345)');\n }\n}\n```\n\n3. **Idempotent migrations**: Design migrations to be safe if run multiple times:\n```sql\n-- Idempotent migration\nCREATE TABLE IF NOT EXISTS users (...);\nCREATE INDEX IF NOT EXISTS idx_users_email ON users(email);\n```\n\n---\n\n### Q5: What's the startup and shutdown order when you run `docker compose down`?\n\n**Answer**: Compose reverses the dependency order for shutdown:\n\n**Startup order** (based on depends_on):\n```\n1. db (no dependencies)\n2. redis (no dependencies)\n3. migrate (depends on db)\n4. api (depends on db, redis, migrate)\n5. worker (depends on api)\n6. nginx (depends on api)\n```\n\n**Shutdown order** (reverse):\n```\n1. nginx (most dependent)\n2. worker\n3. api\n4. migrate (if still running)\n5. db, redis (least dependent)\n```\n\n**Important nuances**:\n- `docker compose down` sends SIGTERM to all containers in reverse dependency order\n- Containers have `stop_grace_period` to finish gracefully\n- After grace period, SIGKILL is sent\n- Networks and volumes are removed last\n\n**Best practice for clean shutdown**:\n```bash\n# Explicit ordered shutdown for production\ndocker compose stop nginx # Stop accepting traffic\nsleep 5 # Drain connections\ndocker compose stop api worker # Stop application\nsleep 10 # Allow graceful shutdown\ndocker compose stop db redis # Stop infrastructure\ndocker compose down # Remove containers\n```\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### Dependency Conditions\n| Condition | Wait For | Use Case |\n|-----------|----------|----------|\n| `service_started` | Container running | Quick services |\n| `service_healthy` | Health check pass | Databases, caches |\n| `service_completed_successfully` | Exit code 0 | Migrations |\n\n### Health Check Best Practices\n- Always include `start_period` for slow-starting services\n- Test actual functionality, not just port availability\n- Use appropriate intervals (5-30s depending on service)\n\n### Graceful Shutdown\n1. Handle SIGTERM in application\n2. Stop accepting new connections\n3. Complete in-flight requests\n4. Close resources (DB, cache)\n5. Exit cleanly\n\n### Startup Order\n```\nInfrastructure → Setup → Application → Proxy\n```\n\n### Shutdown Order\n```\nProxy → Application → Setup → Infrastructure\n```\n\n---\n\n## 📋 Quick Reference\n\n```yaml\n# Health-based dependency\ndepends_on:\n db:\n condition: service_healthy\n\n# Complete health check\nhealthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n interval: 10s\n timeout: 5s\n retries: 3\n start_period: 30s\n\n# Graceful shutdown\nstop_signal: SIGTERM\nstop_grace_period: 30s\n\n# One-time service\nrestart: \"no\"\ndepends_on:\n db:\n condition: service_healthy\n```\n\n---\n\n## 📅 Review Schedule\n\n- **Day 1**: Practice depends_on with conditions\n- **Day 3**: Implement health checks for your services\n- **Day 7**: Add graceful shutdown handling\n- **Day 14**: Design complete startup/shutdown flow\n- **Day 30**: Audit production compose files\n\n---\n\n## 📚 Series Navigation\n\n- **Previous**: [Part 14 - Compose File Deep Dive](/articles/docker-part-14-compose-deep-dive)\n- **Next**: [Part 16 - Development vs Production Compose](/articles/docker-part-16-dev-vs-prod)\n- **Index**: [Docker Compendium Series](/series/docker-compendium)","2026-06-10T07:19:25.535852Z","2026-06-10T07:19:25.536469Z",15,{"_34":16,"_96":59,"_97":98,"_99":100,"_101":-5,"_102":-5,"_103":-5,"_104":-5,"_105":-5},{"_34":92,"_74":61,"_38":93,"_77":94,"_95":-5},[118,119,120],{"_34":16,"_74":75,"_38":76,"_77":78,"_79":24},{"_34":89,"_74":90,"_38":91},{"_34":83,"_74":84,"_38":85},{"_34":121,"_74":122,"_38":123},243,"Orchestration","orchestration",66,"Development vs Production Compose","docker-part-16-dev-vs-prod","Override files, env-specific configs, secrets","## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| **Difficulty** | 🟡 Intermediate |\n| **Prerequisites** | Part 14 (Compose Deep Dive), Part 15 (Dependencies) |\n| **Key Patterns** | Override files, profiles, multi-stage builds |\n| **Time Investment** | 25 minutes read + 60 minutes practice |\n| **Payoff** | Same codebase works perfectly in dev and prod |\n\n---\n\n## 🎯 What You'll Learn\n\nAfter this article, you'll be able to:\n\n1. **Structure compose files** for multiple environments\n2. **Configure development** with hot reload, debugging, and local tools\n3. **Configure production** with security, performance, and reliability\n4. **Handle secrets** differently across environments\n5. **Implement environment parity** while maintaining dev productivity\n\n---\n\n## 🔥 Production Story: The \"Works on My Machine\" Disaster\n\n**The Setup**: A team used one compose file for everything. Development worked great. Production... not so much.\n\n**The Problem Compose File**:\n```yaml\nservices:\n api:\n build: .\n volumes:\n - .:/app # Great for dev hot reload\n - /app/node_modules\n ports:\n - \"3000:3000\"\n - \"9229:9229\" # Debug port exposed!\n environment:\n - DEBUG=true\n - NODE_ENV=development\n command: npm run dev # Nodemon in production!\n```\n\n**What Went Wrong**:\n1. Volume mount `.:/app` overwrote production code with empty directory\n2. Debug port `9229` exposed to internet\n3. `DEBUG=true` leaked sensitive information in logs\n4. `npm run dev` ran nodemon instead of production server\n5. No resource limits caused OOM under load\n\n**The Fix**: Separate development and production configurations that share a common base.\n\n---\n\n## 🧠 Mental Model: Environment Layering\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ COMPOSE FILE LAYERING │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ BASE LAYER (docker-compose.yml) │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ • Service definitions │ │\n│ │ • Network topology │ │\n│ │ • Volume definitions │ │\n│ │ • Health checks │ │\n│ │ • Common environment variables │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ ↓ │\n│ DEV OVERRIDE (docker-compose.override.yml) │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ • build context (instead of image) │ │\n│ │ • Volume mounts for hot reload │ │\n│ │ • Debug ports exposed │ │\n│ │ • DEV environment variables │ │\n│ │ • Local database ports exposed │ │\n│ │ • Dev tools (pgadmin, redis-commander) │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n│ PROD OVERRIDE (docker-compose.prod.yml) │\n│ ┌─────────────────────────────────────────────────────────┐ │\n│ │ • Pre-built images │ │\n│ │ • No volume mounts (except data) │ │\n│ │ • Resource limits │ │\n│ │ • Production logging │ │\n│ │ • Security hardening │ │\n│ │ • Replicas for scaling │ │\n│ └─────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n\nAuto-loaded: compose.yml + compose.override.yml\nProduction: compose.yml + compose.prod.yml\nStaging: compose.yml + compose.staging.yml\nTesting: compose.yml + compose.test.yml\n```\n\n---\n\n## 🔬 Deep Dive\n\n### 1. File Structure and Naming\n\n**Recommended Directory Structure**:\n\n```\nproject/\n├── docker-compose.yml # Base configuration\n├── docker-compose.override.yml # Development (auto-loaded)\n├── docker-compose.prod.yml # Production\n├── docker-compose.staging.yml # Staging (optional)\n├── docker-compose.test.yml # Testing\n├── .env # Default environment\n├── .env.example # Template for .env\n├── .env.production # Production env (gitignored)\n├── Dockerfile # Multi-stage Dockerfile\n└── docker/\n ├── nginx/\n │ └── nginx.conf\n └── scripts/\n └── entrypoint.sh\n```\n\n**Naming Conventions**:\n\n```bash\n# Compose V2 supports both naming styles\ndocker-compose.yml # Classic style\ncompose.yml # New style (Compose V2)\n\n# Override files\ndocker-compose.override.yml # Auto-loaded with base\ncompose.override.yml # Also auto-loaded\n\n# Environment-specific\ndocker-compose.prod.yml\ndocker-compose.staging.yml\ndocker-compose.test.yml\n```\n\n---\n\n### 2. Base Configuration (docker-compose.yml)\n\nThe base file contains everything common across all environments:\n\n```yaml\n# docker-compose.yml - Base configuration\n\nx-common: &common\n restart: unless-stopped\n logging:\n driver: json-file\n options:\n max-size: \"10m\"\n max-file: \"3\"\n\nservices:\n # ═══════════════════════════════════════════════════════════════\n # API SERVICE\n # ═══════════════════════════════════════════════════════════════\n api:\n <<: *common\n # Image specified in override files\n environment:\n - NODE_ENV=${NODE_ENV:-development}\n - PORT=8080\n - DATABASE_URL=${DATABASE_URL}\n - REDIS_URL=redis://redis:6379\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_started\n healthcheck:\n test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8080/health\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n networks:\n - frontend\n - backend\n\n # ═══════════════════════════════════════════════════════════════\n # WORKER SERVICE\n # ═══════════════════════════════════════════════════════════════\n worker:\n <<: *common\n environment:\n - NODE_ENV=${NODE_ENV:-development}\n - DATABASE_URL=${DATABASE_URL}\n - REDIS_URL=redis://redis:6379\n depends_on:\n db:\n condition: service_healthy\n redis:\n condition: service_started\n networks:\n - backend\n\n # ═══════════════════════════════════════════════════════════════\n # DATABASE\n # ═══════════════════════════════════════════════════════════════\n db:\n <<: *common\n image: postgres:16-alpine\n environment:\n POSTGRES_USER: ${POSTGRES_USER:-app}\n POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Required}\n POSTGRES_DB: ${POSTGRES_DB:-app}\n volumes:\n - pgdata:/var/lib/postgresql/data\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U ${POSTGRES_USER:-app}\"]\n interval: 10s\n timeout: 5s\n retries: 5\n networks:\n - backend\n\n # ═══════════════════════════════════════════════════════════════\n # REDIS\n # ═══════════════════════════════════════════════════════════════\n redis:\n <<: *common\n image: redis:7-alpine\n command: redis-server --appendonly yes\n volumes:\n - redisdata:/data\n healthcheck:\n test: [\"CMD\", \"redis-cli\", \"ping\"]\n interval: 10s\n timeout: 5s\n retries: 5\n networks:\n - backend\n\n# ═══════════════════════════════════════════════════════════════\n# NETWORKS\n# ═══════════════════════════════════════════════════════════════\nnetworks:\n frontend:\n driver: bridge\n backend:\n driver: bridge\n internal: true # No external access\n\n# ═══════════════════════════════════════════════════════════════\n# VOLUMES\n# ═══════════════════════════════════════════════════════════════\nvolumes:\n pgdata:\n redisdata:\n```\n\n---\n\n### 3. Development Override (docker-compose.override.yml)\n\nDevelopment focuses on productivity: hot reload, debugging, easy database access:\n\n```yaml\n# docker-compose.override.yml - Development configuration\n# Auto-loaded with docker-compose.yml\n\nservices:\n # ═══════════════════════════════════════════════════════════════\n # API - Development Mode\n # ═══════════════════════════════════════════════════════════════\n api:\n build:\n context: .\n target: development # Use dev stage from multi-stage Dockerfile\n volumes:\n # Hot reload: mount source code\n - .:/app\n # Preserve node_modules from container (don't overwrite with host's)\n - /app/node_modules\n ports:\n - \"8080:8080\" # API port\n - \"9229:9229\" # Debug port\n environment:\n - DEBUG=*\n - LOG_LEVEL=debug\n command: npm run dev # Nodemon or similar\n\n # ═══════════════════════════════════════════════════════════════\n # WORKER - Development Mode\n # ═══════════════════════════════════════════════════════════════\n worker:\n build:\n context: .\n target: development\n volumes:\n - .:/app\n - /app/node_modules\n environment:\n - DEBUG=*\n - LOG_LEVEL=debug\n command: npm run worker:dev\n\n # ═══════════════════════════════════════════════════════════════\n # DATABASE - Expose for local tools\n # ═══════════════════════════════════════════════════════════════\n db:\n ports:\n - \"5432:5432\" # Access from host\n environment:\n - POSTGRES_PASSWORD=devpassword # Simple dev password\n\n # ═══════════════════════════════════════════════════════════════\n # REDIS - Expose for local tools\n # ═══════════════════════════════════════════════════════════════\n redis:\n ports:\n - \"6379:6379\"\n\n # ═══════════════════════════════════════════════════════════════\n # DEV TOOLS (profiles ensure they're opt-in)\n # ═══════════════════════════════════════════════════════════════\n pgadmin:\n image: dpage/pgadmin4:latest\n environment:\n PGADMIN_DEFAULT_EMAIL: dev@local.dev\n PGADMIN_DEFAULT_PASSWORD: devpassword\n ports:\n - \"5050:80\"\n networks:\n - backend\n profiles:\n - tools\n\n redis-commander:\n image: rediscommander/redis-commander:latest\n environment:\n REDIS_HOSTS: local:redis:6379\n ports:\n - \"8081:8081\"\n networks:\n - backend\n profiles:\n - tools\n\n mailhog:\n image: mailhog/mailhog:latest\n ports:\n - \"1025:1025\" # SMTP\n - \"8025:8025\" # Web UI\n networks:\n - backend\n profiles:\n - tools\n```\n\n**Development .env file**:\n\n```bash\n# .env (development, committed to repo)\nNODE_ENV=development\nPOSTGRES_USER=app\nPOSTGRES_PASSWORD=devpassword\nPOSTGRES_DB=app\nDATABASE_URL=postgres://app:devpassword@db:5432/app\nLOG_LEVEL=debug\n```\n\n**Running Development**:\n\n```bash\n# Start everything (auto-loads override)\ndocker compose up\n\n# Start with dev tools\ndocker compose --profile tools up\n\n# Rebuild after dependency changes\ndocker compose up --build\n\n# View logs\ndocker compose logs -f api\n```\n\n---\n\n### 4. Production Override (docker-compose.prod.yml)\n\nProduction focuses on security, reliability, and performance:\n\n```yaml\n# docker-compose.prod.yml - Production configuration\n\nservices:\n # ═══════════════════════════════════════════════════════════════\n # API - Production Mode\n # ═══════════════════════════════════════════════════════════════\n api:\n image: ${REGISTRY}/api:${VERSION}\n # NO build context - use pre-built image\n # NO volumes - code baked into image\n # NO debug ports\n environment:\n - NODE_ENV=production\n - LOG_LEVEL=info\n - DEBUG= # Explicitly empty\n deploy:\n mode: replicated\n replicas: 2\n resources:\n limits:\n cpus: '1'\n memory: 512M\n reservations:\n cpus: '0.5'\n memory: 256M\n update_config:\n parallelism: 1\n delay: 10s\n order: start-first\n logging:\n driver: json-file\n options:\n max-size: \"50m\"\n max-file: \"5\"\n tag: \"{{.Name}}/{{.ID}}\"\n security_opt:\n - no-new-privileges:true\n read_only: true\n tmpfs:\n - /tmp:size=100M,mode=1777\n\n # ═══════════════════════════════════════════════════════════════\n # WORKER - Production Mode\n # ═══════════════════════════════════════════════════════════════\n worker:\n image: ${REGISTRY}/worker:${VERSION}\n environment:\n - NODE_ENV=production\n - LOG_LEVEL=info\n - CONCURRENCY=10\n deploy:\n mode: replicated\n replicas: 2\n resources:\n limits:\n cpus: '0.5'\n memory: 256M\n security_opt:\n - no-new-privileges:true\n\n # ═══════════════════════════════════════════════════════════════\n # DATABASE - Production hardening\n # ═══════════════════════════════════════════════════════════════\n db:\n # NO exposed ports in production\n ports: []\n deploy:\n resources:\n limits:\n cpus: '2'\n memory: 2G\n environment:\n # Password from secrets manager in real prod\n POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Required}\n\n # ═══════════════════════════════════════════════════════════════\n # REDIS - Production hardening\n # ═══════════════════════════════════════════════════════════════\n redis:\n ports: []\n command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru\n deploy:\n resources:\n limits:\n memory: 300M\n\n # ═══════════════════════════════════════════════════════════════\n # NGINX - Reverse Proxy (production only)\n # ═══════════════════════════════════════════════════════════════\n nginx:\n image: nginx:alpine\n ports:\n - \"80:80\"\n - \"443:443\"\n volumes:\n - ./docker/nginx/nginx.prod.conf:/etc/nginx/nginx.conf:ro\n - ./docker/nginx/ssl:/etc/nginx/ssl:ro\n depends_on:\n api:\n condition: service_healthy\n networks:\n - frontend\n deploy:\n resources:\n limits:\n cpus: '0.5'\n memory: 128M\n security_opt:\n - no-new-privileges:true\n read_only: true\n tmpfs:\n - /var/cache/nginx:size=100M\n - /var/run:size=10M\n```\n\n**Production .env.production file** (gitignored):\n\n```bash\n# .env.production (NOT committed, managed via secrets)\nNODE_ENV=production\nREGISTRY=registry.example.com\nVERSION=1.2.3\nPOSTGRES_USER=app_prod\nPOSTGRES_PASSWORD=\nPOSTGRES_DB=app_prod\nDATABASE_URL=postgres://app_prod:@db:5432/app_prod\n```\n\n**Running Production**:\n\n```bash\n# Explicitly specify files (don't auto-load override)\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n\n# Or set COMPOSE_FILE\nexport COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml\ndocker compose up -d\n\n# Rolling update\ndocker compose pull\ndocker compose up -d --no-deps api\ndocker compose up -d --no-deps worker\n```\n\n---\n\n### 5. Multi-Stage Dockerfile\n\nSingle Dockerfile that serves both development and production:\n\n```dockerfile\n# Dockerfile\n\n# ═══════════════════════════════════════════════════════════════\n# BASE - Common dependencies\n# ═══════════════════════════════════════════════════════════════\nFROM node:20-alpine AS base\n\nWORKDIR /app\n\n# Install production dependencies only\nCOPY package*.json ./\nRUN npm ci --only=production\n\n# ═══════════════════════════════════════════════════════════════\n# DEVELOPMENT - Full dev environment\n# ═══════════════════════════════════════════════════════════════\nFROM node:20-alpine AS development\n\nWORKDIR /app\n\n# Install ALL dependencies (including devDependencies)\nCOPY package*.json ./\nRUN npm ci\n\n# Don't copy source - it will be mounted as volume\n# Install dev tools\nRUN npm install -g nodemon\n\n# Debug port\nEXPOSE 9229\n# App port\nEXPOSE 8080\n\nCMD [\"npm\", \"run\", \"dev\"]\n\n# ═══════════════════════════════════════════════════════════════\n# BUILD - Compile/bundle application\n# ═══════════════════════════════════════════════════════════════\nFROM node:20-alpine AS build\n\nWORKDIR /app\n\n# Need all deps for build\nCOPY package*.json ./\nRUN npm ci\n\n# Copy source and build\nCOPY . .\nRUN npm run build\n\n# ═══════════════════════════════════════════════════════════════\n# PRODUCTION - Minimal runtime\n# ═══════════════════════════════════════════════════════════════\nFROM node:20-alpine AS production\n\nWORKDIR /app\n\n# Non-root user\nRUN addgroup -g 1001 -S nodejs && \\\n adduser -S nodejs -u 1001\n\n# Copy production deps from base\nCOPY --from=base /app/node_modules ./node_modules\n\n# Copy built application from build stage\nCOPY --from=build /app/dist ./dist\nCOPY --from=build /app/package.json ./\n\n# Security hardening\nUSER nodejs\n\nEXPOSE 8080\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=10s --retries=3 \\\n CMD wget -q --spider http://localhost:8080/health || exit 1\n\nCMD [\"node\", \"dist/server.js\"]\n```\n\n**Usage in compose**:\n\n```yaml\n# Development (override)\napi:\n build:\n context: .\n target: development\n\n# Production\napi:\n image: registry/api:${VERSION}\n # Or build:\n build:\n context: .\n target: production\n```\n\n---\n\n### 6. Environment-Specific Secrets\n\n**Development**: Simple, committed secrets (okay for local dev):\n\n```yaml\n# docker-compose.override.yml\nservices:\n api:\n environment:\n - JWT_SECRET=dev-secret-not-for-production\n - API_KEY=dev-api-key\n```\n\n**Production**: External secrets (never in compose files):\n\n```yaml\n# docker-compose.prod.yml\nservices:\n api:\n environment:\n # From environment variable (CI/CD injects)\n - JWT_SECRET=${JWT_SECRET:?Required}\n - API_KEY=${API_KEY:?Required}\n\n # Or using Docker secrets (Swarm mode)\n secrets:\n - jwt_secret\n - api_key\n\nsecrets:\n jwt_secret:\n external: true\n api_key:\n external: true\n```\n\n**Docker Secrets Pattern**:\n\n```bash\n# Create secrets (Swarm mode)\necho \"super-secret-jwt-key\" | docker secret create jwt_secret -\n\n# In application, read from /run/secrets/\nconst jwtSecret = fs.readFileSync('/run/secrets/jwt_secret', 'utf8').trim();\n```\n\n**Environment Variables from File**:\n\n```yaml\n# docker-compose.prod.yml\nservices:\n api:\n env_file:\n - .env.production\n```\n\n---\n\n### 7. Testing Configuration\n\nTesting needs isolation and speed:\n\n```yaml\n# docker-compose.test.yml\n\nservices:\n api:\n build:\n context: .\n target: development\n environment:\n - NODE_ENV=test\n - DATABASE_URL=postgres://test:test@db-test:5432/test\n - REDIS_URL=redis://redis-test:6379\n depends_on:\n db-test:\n condition: service_healthy\n redis-test:\n condition: service_started\n networks:\n - test\n\n # Separate test databases\n db-test:\n image: postgres:16-alpine\n environment:\n POSTGRES_USER: test\n POSTGRES_PASSWORD: test\n POSTGRES_DB: test\n healthcheck:\n test: pg_isready -U test\n interval: 5s\n timeout: 5s\n retries: 5\n # tmpfs for speed\n tmpfs:\n - /var/lib/postgresql/data\n networks:\n - test\n\n redis-test:\n image: redis:7-alpine\n networks:\n - test\n\n # Test runner\n test-runner:\n build:\n context: .\n target: development\n command: npm test\n environment:\n - NODE_ENV=test\n - DATABASE_URL=postgres://test:test@db-test:5432/test\n depends_on:\n api:\n condition: service_healthy\n networks:\n - test\n\nnetworks:\n test:\n driver: bridge\n```\n\n**Running Tests**:\n\n```bash\n# Run tests in isolated environment\ndocker compose -f docker-compose.yml -f docker-compose.test.yml run --rm test-runner\n\n# CI/CD pipeline\ndocker compose -f docker-compose.yml -f docker-compose.test.yml up -d db-test redis-test\ndocker compose -f docker-compose.yml -f docker-compose.test.yml run --rm test-runner\ndocker compose -f docker-compose.yml -f docker-compose.test.yml down -v\n```\n\n---\n\n### 8. Complete Example: Makefile for Environment Management\n\n```makefile\n# Makefile\n\n.PHONY: dev dev-tools prod test clean\n\n# Development (auto-loads override)\ndev:\n\tdocker compose up\n\ndev-build:\n\tdocker compose up --build\n\ndev-tools:\n\tdocker compose --profile tools up\n\n# Production\nprod:\n\tdocker compose -f docker-compose.yml -f docker-compose.prod.yml up -d\n\nprod-build:\n\tdocker compose -f docker-compose.yml -f docker-compose.prod.yml build\n\nprod-deploy:\n\tdocker compose -f docker-compose.yml -f docker-compose.prod.yml pull\n\tdocker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --no-deps api worker\n\n# Testing\ntest:\n\tdocker compose -f docker-compose.yml -f docker-compose.test.yml run --rm test-runner\n\tdocker compose -f docker-compose.yml -f docker-compose.test.yml down -v\n\ntest-watch:\n\tdocker compose -f docker-compose.yml -f docker-compose.test.yml run --rm test-runner npm run test:watch\n\n# Cleanup\nclean:\n\tdocker compose down -v --remove-orphans\n\tdocker compose -f docker-compose.yml -f docker-compose.test.yml down -v --remove-orphans\n\n# Logs\nlogs:\n\tdocker compose logs -f\n\nlogs-api:\n\tdocker compose logs -f api\n\n# Shell access\nshell-api:\n\tdocker compose exec api sh\n\nshell-db:\n\tdocker compose exec db psql -U app\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Same Dockerfile CMD for Dev and Prod\n\n```dockerfile\n# ❌ Wrong: Production runs dev server\nCMD [\"npm\", \"run\", \"dev\"]\n\n# ✅ Right: Different targets\n# Development stage\nFROM base AS development\nCMD [\"npm\", \"run\", \"dev\"]\n\n# Production stage\nFROM base AS production\nCMD [\"npm\", \"start\"]\n```\n\n### Mistake 2: Volume Mount in Production\n\n```yaml\n# ❌ Wrong: Mounts empty host directory over container code\nservices:\n api:\n volumes:\n - .:/app # Fine in dev, disaster in prod\n\n# ✅ Right: Only in development override\n# docker-compose.yml: No volume mounts\n# docker-compose.override.yml:\nservices:\n api:\n volumes:\n - .:/app\n```\n\n### Mistake 3: Exposing Debug Ports in Production\n\n```yaml\n# ❌ Wrong: Debug port in base file\nservices:\n api:\n ports:\n - \"8080:8080\"\n - \"9229:9229\" # Debug - should only be in dev!\n\n# ✅ Right: Debug port only in dev override\n# docker-compose.yml:\nservices:\n api:\n ports:\n - \"8080:8080\"\n\n# docker-compose.override.yml:\nservices:\n api:\n ports:\n - \"9229:9229\" # Add debug port for dev\n```\n\n### Mistake 4: Hardcoded Development Settings\n\n```yaml\n# ❌ Wrong: Dev settings in base\nservices:\n api:\n environment:\n - DEBUG=true\n - LOG_LEVEL=debug\n\n# ✅ Right: Use environment variables with defaults\nservices:\n api:\n environment:\n - DEBUG=${DEBUG:-false}\n - LOG_LEVEL=${LOG_LEVEL:-info}\n```\n\n### Mistake 5: No Resource Limits in Production\n\n```yaml\n# ❌ Wrong: No limits - one service can starve others\nservices:\n api:\n image: myapi\n\n# ✅ Right: Always set limits in production\nservices:\n api:\n image: myapi\n deploy:\n resources:\n limits:\n cpus: '1'\n memory: 512M\n```\n\n---\n\n## 🐛 Debug This\n\nDevelopment works, production fails:\n\n```yaml\n# docker-compose.yml\nservices:\n api:\n build: .\n environment:\n - DATABASE_URL=${DATABASE_URL}\n volumes:\n - .:/app\n\n# docker-compose.prod.yml\nservices:\n api:\n image: myapi:${VERSION}\n```\n\n```bash\n# Development: works\n$ docker compose up\napi_1 | Server running on port 8080\n\n# Production: fails\n$ docker compose -f docker-compose.yml -f docker-compose.prod.yml up\napi_1 | Error: Cannot find module '/app/server.js'\n```\n\nWhy does production fail?\n\n

Click to reveal analysis

\n\n**Problem**: Volume mount from base file persists into production!\n\n```yaml\n# docker-compose.yml has:\nvolumes:\n - .:/app # This overrides the container's /app\n\n# Production server likely doesn't have the source code at .\n# The volume mount overwrites the image's /app with an empty or wrong directory\n```\n\n**Compose merge rules**: Arrays (like volumes) are **appended**, not replaced. The production override doesn't remove the volume mount.\n\n**Fix Option 1**: Move volume to dev-only override:\n\n```yaml\n# docker-compose.yml (base)\nservices:\n api:\n environment:\n - DATABASE_URL=${DATABASE_URL}\n # NO volumes here\n\n# docker-compose.override.yml (dev)\nservices:\n api:\n build: .\n volumes:\n - .:/app\n - /app/node_modules\n\n# docker-compose.prod.yml\nservices:\n api:\n image: myapi:${VERSION}\n # No volumes needed\n```\n\n**Fix Option 2**: Explicitly clear volumes in prod:\n\n```yaml\n# docker-compose.prod.yml\nservices:\n api:\n image: myapi:${VERSION}\n volumes: [] # Explicitly empty\n```\n\nNote: `volumes: []` doesn't work in all compose versions. Best practice is to not have dev-only settings in the base file.\n\n

\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Basic Environment Split\nTake this single compose file and split it into base + dev override:\n```yaml\nservices:\n api:\n build: .\n volumes:\n - .:/app\n ports:\n - \"3000:3000\"\n - \"9229:9229\"\n environment:\n - DEBUG=true\n command: npm run dev\n```\n\n### Exercise 2: Production Hardening\nCreate a `docker-compose.prod.yml` that:\n- Uses pre-built images\n- Adds resource limits\n- Enables read-only filesystem\n- Removes debug settings\n- Adds nginx as reverse proxy\n\n### Exercise 3: Multi-Stage Dockerfile\nCreate a multi-stage Dockerfile with:\n- `development` target with all dev tools\n- `build` target that compiles the app\n- `production` target that's minimal and secure\n\n### Exercise 4: Test Configuration\nCreate `docker-compose.test.yml` that:\n- Uses separate test database (tmpfs for speed)\n- Runs tests in isolation\n- Cleans up after itself\n\n### Exercise 5: Secrets Management\nImplement different secret handling for:\n- Development: Simple env vars\n- Production: Docker secrets or external secrets manager\n\n---\n\n## 🎤 Interview Questions\n\n### Q1: How do you structure compose files for multiple environments?\n\n**Answer**: Use layered compose files with automatic and explicit loading:\n\n```\nproject/\n├── docker-compose.yml # Base (always loaded)\n├── docker-compose.override.yml # Dev (auto-loaded locally)\n├── docker-compose.prod.yml # Production\n├── docker-compose.test.yml # Testing\n```\n\n**Loading behavior**:\n```bash\n# Development (auto-loads override)\ndocker compose up\n\n# Production (explicit files)\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up\n\n# Or via environment variable\nCOMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml docker compose up\n```\n\n**Key principles**:\n1. Base file: Service definitions, networks, health checks\n2. Dev override: Build context, volume mounts, debug ports\n3. Prod override: Images, resource limits, security hardening\n\n---\n\n### Q2: What should be in the base compose file vs environment-specific overrides?\n\n**Answer**:\n\n**Base file (docker-compose.yml)**:\n- Service names and structure\n- Network topology\n- Volume definitions (without mounts)\n- Health checks\n- Dependencies\n- Environment variables using `${VAR:-default}` pattern\n\n**Development override**:\n- `build:` context (build from source)\n- Volume mounts for hot reload\n- Debug ports (9229, etc.)\n- Dev tools (pgadmin, etc.)\n- Database ports exposed\n- `DEBUG=true`, verbose logging\n\n**Production override**:\n- `image:` (pre-built images)\n- Resource limits\n- Security options (read_only, no-new-privileges)\n- Production logging config\n- Replicas for scaling\n- Reverse proxy configuration\n\n---\n\n### Q3: How do you handle secrets differently in development vs production?\n\n**Answer**: Different strategies for different security needs:\n\n**Development** (convenience over security):\n```yaml\n# docker-compose.override.yml\nservices:\n api:\n environment:\n - JWT_SECRET=dev-not-secret\n - DB_PASSWORD=devpassword\n```\n\n**Production** (security first):\n\nOption 1 - Environment variables from CI/CD:\n```yaml\n# docker-compose.prod.yml\nservices:\n api:\n environment:\n - JWT_SECRET=${JWT_SECRET:?Required}\n```\n\nOption 2 - Docker secrets (Swarm):\n```yaml\nservices:\n api:\n secrets:\n - jwt_secret\n\nsecrets:\n jwt_secret:\n external: true\n```\n\nOption 3 - External secrets manager:\n```yaml\nservices:\n api:\n environment:\n # App fetches from vault/AWS Secrets Manager at runtime\n - VAULT_ADDR=https://vault:8200\n - VAULT_ROLE=api\n```\n\n**Best practice**: Never commit production secrets. Use CI/CD secret injection or external secrets management.\n\n---\n\n### Q4: How do you ensure development environment matches production?\n\n**Answer**: Environment parity with controlled differences:\n\n1. **Same base services**:\n```yaml\n# docker-compose.yml\nservices:\n db:\n image: postgres:16-alpine # Same version\n redis:\n image: redis:7-alpine # Same version\n```\n\n2. **Same network topology**:\n```yaml\nnetworks:\n frontend:\n backend:\n internal: true # Same isolation\n```\n\n3. **Multi-stage Dockerfile**:\n```dockerfile\n# Same base, different targets\nFROM node:20-alpine AS base\n# ...\nFROM base AS development\nFROM base AS production\n```\n\n4. **Controlled differences** (documented):\n- Dev: Volume mounts, debug ports, verbose logging\n- Prod: Resource limits, security hardening, monitoring\n\n5. **Same configurations**:\n```yaml\n# Share health checks, timeouts, retry policies\nx-healthcheck: &healthcheck\n interval: 30s\n timeout: 10s\n retries: 3\n```\n\n---\n\n### Q5: How would you debug an issue that only happens in production compose setup?\n\n**Answer**: Systematic approach to reproduce and diagnose:\n\n1. **Run production config locally**:\n```bash\n# Use prod config without prod secrets\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml \\\n --env-file .env.local up\n```\n\n2. **Compare configurations**:\n```bash\n# Generate resolved config\ndocker compose config > dev-resolved.yml\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml config > prod-resolved.yml\ndiff dev-resolved.yml prod-resolved.yml\n```\n\n3. **Check for common issues**:\n- Volume mounts persisting from base (overwriting image contents)\n- Missing environment variables (required in prod)\n- Resource limits causing OOM\n- Network isolation blocking communication\n- Read-only filesystem blocking temp files\n\n4. **Inspect running containers**:\n```bash\ndocker compose exec api env # Check environment\ndocker compose exec api ls -la /app # Check filesystem\ndocker compose logs api # Check logs\n```\n\n5. **Add debug temporarily**:\n```yaml\n# Temporary debug override\nservices:\n api:\n environment:\n - LOG_LEVEL=debug\n # Temporarily remove read_only for debugging\n read_only: false\n```\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### File Structure\n```\ndocker-compose.yml # Base (services, networks, volumes)\ndocker-compose.override.yml # Dev (auto-loaded)\ndocker-compose.prod.yml # Production (explicit)\n```\n\n### Development Config\n- Build from source\n- Volume mounts for hot reload\n- Debug ports exposed\n- Databases accessible\n- Verbose logging\n\n### Production Config\n- Pre-built images\n- No volume mounts (except data)\n- Resource limits\n- Security hardening\n- Minimal logging\n\n### Running Commands\n```bash\n# Dev (auto-loads override)\ndocker compose up\n\n# Prod (explicit files)\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up\n```\n\n---\n\n## 📋 Quick Reference\n\n```yaml\n# Base: Use variables with defaults\nenvironment:\n - NODE_ENV=${NODE_ENV:-development}\n\n# Dev: Build and mount\nbuild:\n context: .\n target: development\nvolumes:\n - .:/app\n\n# Prod: Image and limits\nimage: registry/app:${VERSION}\ndeploy:\n resources:\n limits:\n memory: 512M\nread_only: true\nsecurity_opt:\n - no-new-privileges:true\n```\n\n---\n\n## 📅 Review Schedule\n\n- **Day 1**: Split existing compose into base + override\n- **Day 3**: Add production override with security\n- **Day 7**: Implement multi-stage Dockerfile\n- **Day 14**: Set up complete dev/test/prod pipeline\n- **Day 30**: Audit production configs for security\n\n---\n\n## 📚 Series Navigation\n\n- **Previous**: [Part 15 - Service Dependencies & Orchestration](/articles/docker-part-15-dependencies)\n- **Next**: [Part 17 - CI/CD Pipeline Patterns](/articles/docker-part-17-cicd)\n- **Index**: [Docker Compendium Series](/series/docker-compendium)","2026-06-10T07:19:25.546187Z","2026-06-10T07:19:25.546800Z",{"_34":16,"_96":59,"_97":98,"_99":100,"_101":-5,"_102":-5,"_103":-5,"_104":-5,"_105":-5},{"_34":92,"_74":61,"_38":93,"_77":94,"_95":-5},[135,136,137],{"_34":16,"_74":75,"_38":76,"_77":78,"_79":24},{"_34":89,"_74":90,"_38":91},{"_34":83,"_74":84,"_38":85},{"_34":138,"_74":139,"_38":140},216,"Production","production"]