Docker Compose Tutorial: Service Orchestration in Practice

Stop Wrapping Multi-Container Apps in Endless docker run Calls

Nginx, an API, PostgreSQL, and Redis started one docker run at a time means hand-managing ports, volumes, networking, environment variables, and startup order — dozens of flags per command, none of it versioned. Compose describes the whole stack in one declarative YAML file, starts, stops, and rebuilds it with one command, and keeps the config in Git.

Docker Desktop bundles Compose. On Linux install docker-compose-plugin and use docker compose (V2) rather than the unmaintained docker-compose (V1).

Core Concepts

Services and the Default Network

Each service defines one container. Compose creates a network per project, and services in the same file reach each other by service name with no IP bookkeeping:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html
    depends_on:
      - api
  api:
    image: node:20-alpine
    # inside web: http://api:3000

For tier isolation, define custom networks: put web and api on frontend, db only on backend, and web can no longer reach the database.

services:
  web:
    networks: [frontend]
  api:
    networks: [frontend, backend]
  db:
    networks: [backend]

networks:
  frontend:
  backend:

Volumes: Named Volume vs Bind Mount

Type Syntax Use for
Named volume name:/path/in/container Runtime data such as databases; survives container removal
Bind mount ./host/path:/container/path Syncing source and config during development
services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

volumes:
  pgdata:

A bind mount shadows the container's directory of the same name. Mount ./backend:/app and the node_modules installed in the image disappears behind the host directory, so the container fails with a missing module. Add an anonymous volume - /app/node_modules to keep the image's dependencies.

Environment: Interpolation Is Not Injection

services:
  api:
    image: myapp:latest
    environment:
      - NODE_ENV=production
    env_file:
      - .env

${VAR} is substituted while parsing the YAML, for the compose file's own use. environment and env_file are injected into the container process at runtime. The two are not interchangeable: a DB_PASSWORD in .env does not reach the container unless it is also listed under environment.

.env must sit in the directory where you run docker compose (usually the project root), not next to the compose file in a subdirectory. Debug with docker compose config, which prints the merged, interpolated result so you can see whether substitution happened.

In Practice: Nginx + Node + PostgreSQL + Redis

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - api
    restart: unless-stopped

  api:
    build:
      context: ./backend
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgresql://app:${DB_PASSWORD}@db:5432/app
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redisdata:/data
    restart: unless-stopped

volumes:
  pgdata:
  redisdata:

The reverse-proxy half is covered in the Nginx config cheat sheet.

Everyday Commands

docker compose up -d              # start everything detached
docker compose ps                 # status
docker compose logs -f api        # follow logs
docker compose up -d --build      # rebuild after code changes
docker compose restart api        # restart one service
docker compose exec api sh        # shell into a container
docker compose down               # remove containers and networks, keep volumes
docker compose down -v            # remove volumes too (database data is lost)
docker compose stats              # resource usage

Four Checks Before Shipping

depends_on Starts, It Does Not Mean Ready

The default depends_on waits for the container to start, not for the process to serve. The symptom is familiar: the API boots, connects to the database while it is still initializing, and exits. Add a healthcheck to the dependency and a condition to the dependent:

services:
  api:
    depends_on:
      db:
        condition: service_healthy

service_healthy waits for the check to pass; service_started (the default) waits for nothing meaningful.

Override Files for Multiple Environments

docker compose -f docker-compose.yml -f docker-compose.dev.yml up
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Override files contain only differences — for development, switch command: npm run dev and expose debug port 9229; the production file adjusts resource caps and logging. Do not keep two complete YAML copies, or a change in one will be missed in the other.

Resource Caps and Log Rotation

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Without caps, one container eating all memory can take down the host; without rotation, logs can fill the disk.

Permissions, Ports, and Windows Mounts

  • Linux write errors: the container process UID does not match the host file owner. Align with user: "${UID}:${GID}", or chown from an init container after mounting.
  • Port already allocated: docker compose up fails while docker ps shows nothing. Find the host process with netstat -ano | findstr :8080 (Windows) or lsof -i :8080 (Linux/macOS).
  • Slow Windows mounts: with the WSL2 backend, mounting /c/... carries significant IO overhead. Put the project inside the WSL2 filesystem (\\wsl$\Ubuntu\home\...) — the original test measured 5-10x faster.

When to Move Beyond Compose

Scenario Tool
Single-host development / small deployment Docker Compose
Multi-host cluster / high availability Docker Swarm (lightweight) or Kubernetes
Enterprise production orchestration Kubernetes

Compose handles small single-host production well with restart: unless-stopped, healthchecks, resource caps, and log rotation. What it lacks is multi-node scheduling, autoscaling, rolling updates, and self-healing; migrate when you need multi-host availability. A docker-compose.yml deploys to Swarm via docker stack deploy; Kubernetes needs converted manifests (Kompose helps).

Reproducible Results

docker compose config parses without deploying, so syntax errors, bad indentation, and wrong types surface immediately:

docker compose config -q && echo "compose OK"    # silent + exit 0 when valid
docker compose config                             # final config after interpolation and defaults

Run both before up to skip the "three containers later I notice the port mapping is wrong" loop. Convert command-line flags with the docker run to compose tool, and keep the Docker command cheat sheet handy.

Frequently Asked Questions

Does depends_on guarantee a service is actually ready?

No, and this is the most common misunderstanding. depends_on only guarantees the container has started, not that the process inside is serving traffic — which is why you get the classic failure where the API boots, tries to reach the database, and the database process is not up yet. The fix is to declare a healthcheck on the dependency and use condition: service_healthy (or service_completed_successfully) on the dependent service. Using service_started, the default, is equivalent to not waiting at all.

When should I use a named volume versus a bind mount?

Use named volumes for runtime data you must keep (pgdata:/var/lib/postgresql/data): Docker manages where it lives, the data survives container removal, and on Linux the performance beats a bind mount. Use bind mounts to sync code or config during development (./backend:/app), so edits take effect immediately and hot reload works. Watch out that a bind mount shadows the container's own directory — a common trick is an anonymous volume (- /app/node_modules) to protect dependencies installed inside the image.

Why is my .env file being ignored?

Two causes dominate. First, .env must sit in the directory where you run docker compose (normally the project root), not in a subdirectory next to the compose file. Second, keep clear the difference between variable interpolation ${VAR} (substituted while parsing the YAML, for the compose file's own use) and environment / env_file injection (passed to the container process at runtime) — they are not interchangeable. Debug with docker compose config, which prints the fully merged and interpolated result, so you can see at a glance whether the variable was substituted.

Can I run Docker Compose in production?

Yes for small single-host production deployments — Compose handles that well. Add restart: unless-stopped, healthcheck, resource caps under deploy.resources.limits, log rotation, and environment overlays via -f docker-compose.yml -f docker-compose.prod.yml, and the setup is genuinely solid. What it lacks is multi-node scheduling, autoscaling, rolling updates, and self-healing — once you need multi-host high availability, move to Docker Swarm (lightweight) or Kubernetes (rich ecosystem). A compose file deploys to Swarm directly with docker stack deploy; moving to Kubernetes requires converting the manifests, with tools like Kompose to help.

← Back to Blog