Docker Compose: Bring Up a Full Stack with One Command

Declaring services with a healthcheck and depends_on guarantees the DB is ready before the web app starts.

# compose.yaml
services:
  db:
    image: postgres:16
    environment: { POSTGRES_PASSWORD: secret }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
  web:
    image: nginx:stable
    depends_on:
      db: { condition: service_healthy }
    ports: ["8080:80"]

Expected output:

$ docker compose config --quiet && echo "compose file is valid"
compose file is valid

That minimal file works, but a stack you would actually keep needs more: a named volume so the data survives teardowns, a dedicated network so the database is not exposed to anything but the services that need it, and the cache tier the architecture diagram promised. Here is the full version, with each addition annotated:

compose.yaml, full lab stack

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}   # read from .env, not hardcoded
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data   # survives down/up cycles
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks: [backend]                    # NOT on the frontend network
    restart: unless-stopped

  cache:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks: [backend]

  web:
    image: nginx:stable
    depends_on:
      db:
        condition: service_healthy         # wait for pg_isready, not just start
      cache:
        condition: service_healthy
    ports:
      - "8080:80"                          # host:container
    networks: [frontend, backend]          # web bridges both tiers

networks:
  frontend:
  backend:

volumes:
  db-data:

Two details deserve attention. First, the healthcheck runs inside the container: pg_isready -U postgres asks the local Postgres whether it accepts connections and exits 0 only when it does, and redis-cli ping returns PONG. Without timeout and retries, a single slow probe can leave a service flapping between healthy and unhealthy. Second, web sits on both networks while db and cache sit only on backend, so the only path to the database from outside the stack is through the web tier.

.env, variables interpolated into compose.yaml

DB_PASSWORD=secret

Compose reads .env from the project directory automatically and substitutes ${DB_PASSWORD}. Never commit this file; add it to .gitignore and ship a .env.example with placeholder values instead.

Common mistake: YAML is whitespace-sensitive. A single tab character or a misaligned depends_on key produces a parse error, or worse, silently nests a key one level too deep where Compose ignores it. Verify indentation is consistent two-space before continuing, the next step catches what your eyes miss.

What this teaches: The compose file is the whole stack as data; services, networks, and volumes declared once, reused everywhere.

docker compose config parses the file, resolves variable interpolation, merges any override files, and prints the effective configuration, what Compose will actually act on. Running it before up turns cryptic runtime failures into clean syntax errors, and it is the fastest way to confirm a variable from .env actually landed where you expected.

Note what happened in that output: ${DB_PASSWORD} became secret, and the project name compose-lab was derived from the directory. If the password line still showed a literal ${DB_PASSWORD}, the .env file is missing, misspelled, or in the wrong directory, fix that now, not after the database has initialized itself with an empty password.

How to verify: docker compose config --services should print exactly db, cache, and web, one per line. If one is missing, it failed to parse as a service, usually an indentation problem under services:.

Expected output:

$ docker compose config --services
web
db

What this teaches: Validation before running catches YAML and schema errors while they are still cheap; never debug a running stack for a typo.

The -d flag detaches: containers run in the background and your terminal returns. Without it, Compose streams the aggregated logs of every service to your terminal and tears the stack down when you press Ctrl+C, useful for debugging, annoying for a lab.

Read the output bottom-up and you can see the dependency engine working: networks and the volume are created first, db and cache report Healthy (Compose blocked on their healthchecks), and only then is web started. If you re-run docker compose up -d after editing the file, Compose recreates only the services whose definition changed and leaves the rest untouched.

Common mistake: pulling images on a slow connection makes the first up look hung. It is not, Compose is downloading postgres:16 (~240MB). You can pre-pull with docker compose pull to separate download time from startup time.

For scripts and CI pipelines, prefer docker compose up -d --wait: instead of returning as soon as containers are started, it blocks until every service with a healthcheck reports healthy (and exits non-zero on timeout). That turns "is the stack ready?" from a race-prone sleep 10 into a deterministic gate.

Expected output:

$ docker compose up -d
[+] Running 4/4
 Network compose-lab_default  Created
 Container compose-lab-db-1   Started
 Container compose-lab-web-1  Started

What this teaches: Up is reconciliation: compose creates what is missing and leaves the rest, which makes repeated runs safe.

docker compose ps is scoped to this stack only, unlike docker ps, it will not show unrelated containers on the host. The (healthy) marker next to db and cache comes straight from the healthchecks; if a service shows (unhealthy), its probe is failing and anything with condition: service_healthy will never start.

Follow the logs of one service

docker compose logs -f db

Expected output:

$ docker compose ps
NAME        IMAGE         STATUS
compose-lab-web-1  nginx:1.27    Up 2 minutes
compose-lab-db-1   postgres:16   Up 2 minutes (healthy)

Omit the service name (docker compose logs -f) to follow all services at once, interleaved and colour-coded by service, this is the single most useful debugging view Compose gives you. Add --tail 50 to skip the startup noise, and --since 10m to bound the window when a stack has been running for days.

How to verify: docker compose top shows the actual processes inside each container. The db service should list a postgres process tree; if the container is Up but top shows nothing, the entrypoint crashed and restarted, check docker compose logs db for the reason.

What this teaches: Status and logs are the observability layer; ps shows desired state, logs show actual behavior.

"Up" only means the processes are running. The reason Compose exists is service discovery: each service resolves the others by name through Docker's embedded DNS. Prove it by opening a shell inside the web container and resolving db by name, then exercising each backend with its native client.

Name resolution and port reachability from inside the stack

docker compose exec web getent hosts db
docker compose exec db pg_isready -U postgres
docker compose exec cache redis-cli ping

Expected output:

$ docker compose exec web getent hosts db
172.20.0.3      db

The first command is the important one: the bare hostname db resolved to a container IP on the backend network. That IP changes every time the container is recreated, which is exactly why application configs should reference service names and never addresses. The other two confirm each backend answers on its protocol, not just that its container exists.

Also confirm the segmentation you declared: db has no published port, so it is unreachable from the host, while web is published on 8080:

Common mistake: docker compose exec targets the container by service name (web), not container name (compose-lab-web-1), and it fails with no container found if the service is stopped. Use docker compose run --rm web sh instead when you need a shell in a service that is not currently running.

What this teaches: Service-to-service reachability over the project network is the integration test; DNS names are the service names.

Compose distinguishes four states you will move between constantly. stop halts containers but keeps them (and the data on their volumes); start resumes them; restart is a stop/start pair; down removes containers and networks but keeps named volumes; and down -v removes the volumes too, the full reset.

The lifecycle commands

docker compose stop          # halt, keep everything
docker compose start         # resume halted containers
docker compose restart web   # bounce one service
docker compose down          # remove containers + networks, keep volumes
docker compose down -v       # also delete volumes: data is gone

Expected output:

$ docker compose down
[+] Running 3/3
 Container compose-lab-web-1  Removed
 Container compose-lab-db-1   Removed
 Network compose-lab_default  Removed

Prove the volume did its job: stop the stack, bring it down, start it again, and check that the database still holds data written before the teardown:

The row survived a full container replacement because it lives in the compose-lab_db-data volume, not in the container's writable layer. When you are finished with the lab entirely, docker compose down -v returns the host to a clean state, this is the command to run before resetting the lab for another attempt.

How to verify: after down -v, docker volume ls | grep compose-lab should print nothing, and docker network ls | grep compose-lab should be empty too. Leftovers mean a container from the project is still running somewhere, find it with docker compose ps -a.

What this teaches: Lifecycle commands are the discipline: down without --volumes keeps data, with it starts truly fresh.