compose.yml in Depth

Introduction

The Compose spec is rich: services, networks, volumes, configs, secrets, profiles, healthchecks, deploy hints. You'll touch maybe 20% daily, but knowing what exists pays off when you need it.

Purpose of this lesson

This lesson teaches compose.yml in Depth as an engineering decision: what problem it solves, when to use it, how to implement it safely, and what signals tell you it is failing.

Understanding the topic

Use this when a project has more than one runtime dependency and the team needs a repeatable local, CI, or small-production environment. Compose is most valuable when it replaces tribal setup notes with executable infrastructure.

Core concepts to understand:

• services — one block per container.
• image or build — pre-built vs built from Dockerfile.
• ports, environment, volumes, depends_on.
• profiles let you opt-in services (--profile dev).
• healthcheck + depends_on: condition: service_healthy.

Visual explanation

Architecture or command flow to keep in mind:

services:
  web:
    build: ./web
    ports: ["3000:3000"]
    environment:
      API_URL: http://api:8080
    depends_on:
      api: { condition: service_healthy }
  api:
    build: ./api
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s

Step-by-step explanation

1. Model each service with its own image, ports, environment, healthcheck, networks, and volumes.
2. Keep internal service-to-service traffic on the Compose network and publish only the edge service to the host.
3. Use named volumes for state, bind mounts for local source code, and profiles for optional developer tools.
4. Bring the stack up, read health status and logs, then restart one dependency to see whether the app recovers.
5. Create a production override file with pinned images, restart policies, resource limits, logging, backup, and rollback guidance.

Informative example

Use the example below as a working baseline, then verify the runtime behavior instead of assuming the command or file is correct.

services:
  web:
    build: ./web
    ports: ["3000:3000"]
    environment:
      API_URL: http://api:8080
    depends_on:
      api: { condition: service_healthy }
  api:
    build: ./api
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 10s

A production-minded check usually includes docker ps, docker logs, docker inspect, and one validation from outside the container such as curl, a database connection, or a registry pull.

# Verification loop for compose.yml in Depth
docker ps -a
docker logs --tail=100 <container-name>
docker inspect <container-or-image-name>
docker system df

Real-world use

Health-gated depends_on stops apps from crashing on boot because the DB wasn't ready — saves countless retry loops in CI.

Enterprise use cases

In a mature engineering organization, compose.yml in Depth is documented as a repeatable pattern with approved base images, ownership labels, CI checks, security expectations, rollback notes, and troubleshooting commands. The difference between a tutorial and production practice is that every container decision must be observable, reviewable, and reversible.

Best practices

• Always add healthchecks for services others depend on.
• Group dev-only services (mailhog, adminer) behind a profile.

Debugging tips

• Read logs before restarting; a restart often removes the timing context you need for root cause analysis.
• Use docker inspect to compare configured state with actual runtime state.
• Check daemon health, disk usage, image tags, exit code, and port mappings before blaming application code.

Optimization strategies

• Use profiles to keep optional developer tools out of the default startup path.
• Give long-running services healthchecks and restart policies so failures are visible and recoverable.
• Separate dev and prod overrides instead of stretching one Compose file with fragile conditionals.

Advanced interview questions

Hands-on exercise

Create a small lab for compose.yml in Depth: run the example, inspect the created Docker object, intentionally introduce one mistake, and record the command that reveals the failure. The goal is not just to make the happy path work; it is to build operational reflexes.

# Hands-on lab scaffold
mkdir -p docker-compose-yml-in-depth-lab
cd docker-compose-yml-in-depth-lab

# Add the Dockerfile, compose.yml, or command from this lesson.
# Then run one happy-path test and one broken-path test.
docker version
docker info
docker system df

Summary

compose.yml in Depth matters because Docker is not only a packaging tool; it is a runtime, build, networking, storage, and delivery workflow. Treat each lesson as a production habit: make it repeatable, inspectable, secure, and easy to debug.