The Multi-Container Problem

LEVEL 0

The Problem

Let’s say you’re building a blog application.

You need:

A PostgreSQL database to store posts and users
A Python/Flask application server that reads from the database
An nginx reverse proxy to serve static files and forward requests to Flask
A Redis cache to speed up common queries

On your first attempt, you start these containers manually:

# Create a network
docker network create blog-network

# Start PostgreSQL
docker run -d \
  --name blog-db \
  --network blog-network \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=blog \
  -v blog-db-data:/var/lib/postgresql/data \
  postgres:15

# Wait for it to be ready...

# Start Redis
docker run -d \
  --name blog-cache \
  --network blog-network \
  redis:7

# Start the Flask app
docker run -d \
  --name blog-app \
  --network blog-network \
  -e DATABASE_URL=postgresql://postgres:secret@blog-db:5432/blog \
  -e REDIS_URL=redis://blog-cache:6379 \
  -v $(pwd)/app:/app \
  my-blog-app:latest

# Start nginx
docker run -d \
  --name blog-nginx \
  --network blog-network \
  -p 80:80 \
  -v $(pwd)/nginx.conf:/etc/nginx/nginx.conf \
  nginx:alpine

This works. But look at the problems:

Problem 1: Not repeatable Every time you restart your computer or want to share this with a teammate, you have to run all these commands again. Copy-paste from your notes. Hope you didn’t miss anything.

Problem 2: Order matters The Flask app will fail if PostgreSQL isn’t ready yet. You have to manually wait or add sleep commands. If Redis restarts, the app might not reconnect.

Problem 3: Configuration is scattered Environment variables are on the command line. Volume mounts are hardcoded. If you want to change the PostgreSQL password, you have to find that specific docker run command.

Problem 4: Hard to share Your colleague wants to run the same setup. You send them… what? A shell script? Written instructions? They’re on Windows—$(pwd) doesn’t work the same way.

Problem 5: No lifecycle management Want to stop everything? Four docker stop commands. Want to remove everything? Four docker rm commands. Want to see logs from all services? Multiple terminals with docker logs -f.

Problem 6: Can’t version control commands You can put your Dockerfile and app code in git. But your docker run commands? Those live in a README or a bash script that nobody maintains.

This approach doesn’t scale beyond 2-3 containers.

LEVEL 1

The Concept — The Orchestra Conductor

The Concept

Imagine an orchestra.

You have 30 musicians. Each one has their instrument, their sheet music, their role to play. If each musician showed up at random times, tuned their instrument whenever they felt like it, and started playing without coordination, you’d get chaos.

An orchestra needs a conductor.

The conductor has the score—a document that describes:

What instruments are needed
How many of each
What each should play
When each should start
How they should interact

The conductor doesn’t play the instruments. The conductor doesn’t tell the violinist which notes to play. That’s in the sheet music. The conductor’s job is to ensure everyone starts together, plays in harmony, and follows the same tempo.

Docker Compose is the conductor for your containers.

You write a compose file (the score) that declares:

What containers you need (services)
What images they use
What environment variables they need
What networks connect them
What volumes they use
What order they should start in

Then you run docker compose up, and Compose orchestrates everything. It creates networks, creates volumes, starts containers in the right order, connects them, and ensures they can communicate.

One command. The whole application comes alive.

LEVEL 2

The Mechanics — What Compose Actually Does

The Mechanics

Let’s trace through what happens when you run docker compose up.

Step 1: Parse the compose file

Compose reads docker-compose.yml and builds a model of your application:

Services to create
Networks they need
Volumes they need
Dependencies between them

Step 2: Create networks

For each network defined in the compose file (or a default one if you didn’t specify), Compose runs:

docker network create <project>_<network-name>

Step 3: Create volumes

For each named volume:

docker volume create <project>_<volume-name>

Step 4: Pull images

If images aren’t available locally, Compose pulls them:

docker pull postgres:15
docker pull redis:7

Step 5: Start containers (in order)

Compose creates and starts containers, respecting dependencies. If service A depends on service B, Compose starts B first.

For each service, it effectively runs:

docker run -d \
  --name <project>_<service>_1 \
  --network <project>_<network> \
  [all the environment variables] \
  [all the volume mounts] \
  [all the other config] \
  <image>

Step 6: Attach to logs

By default, docker compose up (without -d) shows you the combined logs from all containers, color-coded by service.

Step 7: Monitor and maintain

Compose monitors the containers. If you Ctrl+C, Compose gracefully stops them all.

LEVEL 3

The Compose File — Declarative Infrastructure

The Compose File

The coordination lives in the compose file. Here’s the blog example from earlier, but as a compose file:

version: '3.9'

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: blog
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - blog-network

  cache:
    image: redis:7
    networks:
      - blog-network

  app:
    build: ./app
    environment:
      DATABASE_URL: postgresql://postgres:secret@db:5432/blog
      REDIS_URL: redis://cache:6379
    volumes:
      - ./app:/app
    depends_on:
      - db
      - cache
    networks:
      - blog-network

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - app
    networks:
      - blog-network

networks:
  blog-network:

volumes:
  db-data:

Now instead of those four docker run commands, you run:

docker compose up

Compose reads the file, creates everything, starts everything, in the right order, with all the configuration applied.

To stop everything:

docker compose down

To see logs:

docker compose logs -f

To rebuild and restart one service:

docker compose up -d --build app

This is declarative infrastructure. You declare what you want, and Compose makes it happen.

LEVEL 4

When to Use Compose

Use Docker Compose when:

✅ You have 2+ containers that work together
✅ You want a reproducible development environment
✅ You’re defining an application stack that others need to run
✅ You want to version-control your infrastructure
✅ You’re tired of long docker run commands
✅ You need to share your setup with teammates

Don’t use Docker Compose when:

❌ You’re running a single standalone container (just use docker run)
❌ You need production-grade orchestration across multiple hosts (use Kubernetes, Docker Swarm)
❌ You need advanced features like auto-scaling, rolling updates, health checks with auto-restart (use Kubernetes)

Compose is perfect for:

Local development environments
CI/CD testing environments
Small production deployments on a single host
Internal tools and services
Demos and prototypes

LEVEL 5

Compose Commands Reference

Once you have a docker-compose.yml file, these are the commands you’ll use daily:

Starting and stopping:

docker compose up          # Start all services (foreground, shows logs)
docker compose up -d       # Start all services (detached/background)
docker compose down        # Stop and remove containers, networks
docker compose stop        # Stop services but don't remove containers
docker compose start       # Start stopped services
docker compose restart     # Restart services

Building and pulling:

docker compose build       # Build/rebuild images for services with 'build' config
docker compose pull        # Pull latest images for all services
docker compose up --build  # Rebuild and start

Managing specific services:

docker compose up db       # Start only the 'db' service (and its dependencies)
docker compose restart app # Restart only the 'app' service
docker compose stop nginx  # Stop only the 'nginx' service

Logs and monitoring:

docker compose logs        # Show logs from all services
docker compose logs -f     # Follow logs (like tail -f)
docker compose logs app    # Show logs only from 'app' service
docker compose ps          # List running services
docker compose top         # Display running processes in services

Executing commands:

docker compose exec app sh           # Open shell in running 'app' container
docker compose exec db psql -U postgres  # Run psql in 'db' container
docker compose run app python test.py   # Run one-off command (creates new container)

Cleanup:

docker compose down            # Remove containers and networks
docker compose down -v         # Also remove volumes
docker compose down --rmi all  # Also remove images

Engine status: planned. The shell remains visible while the artifact execution is prepared.