🐳 Docker Compose Basics

Why Docker Compose?

Docker Compose is a tool for defining and running multi-container applications. You describe your whole system — services, networks, volumes — in one YAML file, then bring it all up (or tear it all down) with a single command. The file becomes the single source of truth that anyone on your team can check out and run identically.

Before Compose, spinning up a web app with a database meant a growing list of imperative commands — create a network, run the database with the right flags, run the API pointing at it, run the web server pointing at that. Miss a flag and nothing connects. Compose turns that fragile ritual into declarative, version-controlled configuration.

When to reach for it

The compose.yaml File

The heart of Compose is a YAML file that declares your services. Modern Compose (the docker compose v2 plugin that ships with Docker Desktop and recent Docker Engine) reads a file named compose.yaml by default. The older docker-compose.yml name still works, but new projects should prefer compose.yaml.

Minimal structure

services:
  web:
    # configuration for the web service

  api:
    # configuration for the api service

volumes:
  # named volumes declared here

networks:
  # custom networks declared here (optional — a default one is created for you)

Only services: is required. volumes: and networks: are declared at the top level when you want named, reusable ones — otherwise Compose creates a default network automatically and connects every service to it.

Anatomy of a Service

Each entry under services: becomes one container. The key you choose (like web or db) is both the container's name and its DNS hostname on the network — that's how services find each other. Here are the options you'll use constantly:

A Real web + api + db Stack

Let's put it all together. This is the classic three-tier layout: an Nginx web front end, a Node.js API built from a local Dockerfile, and a Postgres database whose data survives restarts thanks to a named volume. Study it closely — it's the template you'll adapt for nearly every project.

# compose.yaml — no "version:" key needed in modern Compose
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"              # visit http://localhost:8080
    volumes:
      - ./site:/usr/share/nginx/html:ro   # bind mount static files, read-only
    depends_on:
      - api

  api:
    build: ./api               # builds ./api/Dockerfile
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      # "db" is the service name → Compose resolves it to the db container's IP
      DATABASE_URL: postgres://app:secret@db:5432/appdb
    depends_on:
      db:
        condition: service_healthy   # wait until the DB passes its healthcheck

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - db_data:/var/lib/postgresql/data   # named volume → data persists
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  db_data:                     # declared here so Docker manages it

Three ideas in this file do all the heavy lifting, and they're worth calling out because they're what beginners miss:

• Service-name DNS. The API's DATABASE_URL points at the host db, not localhost. Compose runs an internal DNS server so every service can reach every other by its service name. There is no IP address to hard-code.
• A named volume for the database. db_data lives outside the container's writable layer, so docker compose down and a fresh up keep your rows intact. Bind-mounting the web server's static files (with :ro) is the right call there because those are just files on disk you want to edit live.
• Healthcheck-gated startup. Plain depends_on only waits for the container to start, not for Postgres to be ready to accept connections. Adding condition: service_healthy plus a healthcheck makes the API wait until pg_isready succeeds — eliminating the classic "connection refused" race on the first boot.

Essential Commands

Every command runs from the directory containing your compose.yaml. Here is the daily-driver set — memorize these five and you can run any Compose project.

# Build (if needed) and start everything in the foreground; Ctrl-C to stop
docker compose up

# Start in the background (detached) — the usual choice
docker compose up -d

# Rebuild images before starting (after changing a Dockerfile)
docker compose up -d --build

# See what's running, with status and published ports
docker compose ps

# Follow the combined logs; add a service name to narrow it down
docker compose logs -f
docker compose logs -f api

# Open a shell inside a running service
docker compose exec api sh
docker compose exec db psql -U app -d appdb

# Stop and remove containers + the default network (volumes are KEPT)
docker compose down

# …and also delete named volumes (DESTROYS your database data)
docker compose down -v

The container lifecycle at a glance

NAME          IMAGE          SERVICE   STATUS         PORTS
app-web-1     nginx:alpine   web       Up 2 minutes   0.0.0.0:8080->80/tcp
app-api-1     app-api        api       Up 2 minutes   0.0.0.0:3000->3000/tcp
app-db-1      postgres:16    db        Up 2 minutes   5432/tcp

Environment & .env Files

Hard-coding ports and passwords into compose.yaml is fine for a throwaway demo and a bad habit everywhere else. Compose gives you two complementary tools: a project-level .env file for values it substitutes into the YAML, and the per-service env_file for variables passed into a container.

1. A .env file for substitution

Compose automatically reads a file named .env sitting next to compose.yaml and substitutes ${VARIABLE} references in the YAML:

# .env  (commit a .env.example, never the real secrets)
POSTGRES_PASSWORD=secret
API_PORT=3000
PG_VERSION=16

services:
  api:
    build: ./api
    ports:
      - "${API_PORT}:3000"
  db:
    image: postgres:${PG_VERSION}
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      # Provide a fallback if the variable is unset:
      LOG_LEVEL: ${LOG_LEVEL:-info}

2. env_file for values inside a container

When a service needs a whole batch of variables, point it at a file instead of listing each one:

services:
  api:
    build: ./api
    env_file:
      - ./api/.env.local

Practice & Quiz

# compose.yaml — fill in the blanks
services:
  web:
    image: nginx:alpine
    # TODO: publish container port 80 on host 8080
    # TODO: bind mount ./site read-only into /usr/share/nginx/html

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    # TODO: persist /var/lib/postgresql/data with a named volume

# TODO: declare the named volume

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/postgres
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

Best Practices & Pitfalls

✅ Do

• Name the file compose.yaml and use the docker compose (v2) CLI
• Commit compose.yaml to git alongside your application code
• Use named volumes for databases so data survives down and up
• Keep secrets in a .gitignored .env; commit a redacted .env.example
• Gate depends_on with condition: service_healthy for databases
• Give services clear names — they double as DNS hostnames

❌ Don't

• Add a top-level version: key — it's obsolete and triggers a warning
• Use the hyphenated docker-compose for new work — it's the deprecated v1
• Reach a service via localhost from another container — use the service name
• Run down -v out of habit — it wipes your named volumes
• Assume plain depends_on waits for a database to be ready — it only waits for the container to start

Summary

📚 Additional Resources

• Docker Docs — Docker Compose overview
• Docker Docs — Compose file reference
• Docker Docs — Compose quickstart
• Awesome Compose — real example projects

🚀 What's Next?

You can now define and run a stack. Next we scale that skill up: designing genuinely multi-container applications — service-to-service communication, sensible architecture patterns, and a real e-commerce example that puts several services and databases to work together.