Docker Compose Isn't What I Thought It Was

post 7:

A practical guide to understanding Docker Compose—what it is, how it works, and the misconceptions that catch most beginners.

You've mastered single containers.

Now it's time to build a real application.

A frontend.
A backend.
A database.
A Redis cache.

Suddenly you're juggling multiple docker run commands.

Ports.
Networks.
Volumes.
Environment variables.

Chaos.

Then someone says:

"Just use Docker Compose."

It works beautifully.

But here's the twist most people never realize…

---

Why Docker Compose Exists

Imagine starting an application like this:

• Frontend
• Backend
• PostgreSQL
• Redis

Running each container manually quickly becomes repetitive and error-prone.

Docker Compose lets you describe your entire application in a single YAML file and start everything with one command.

Instead of remembering dozens of commands, you define your infrastructure once.

---

What Docker Compose Actually Is

Docker Compose is not a container orchestrator.

Docker Compose is a tool that reads your Compose YAML file and uses the Docker Engine to create and manage the resources defined in it.”

Modern Docker uses Compose V2, which runs as:

docker compose

instead of the older:

docker-compose

Compose runs only when you execute a command.

It creates the required Docker resources, starts the containers, and then exits.

This makes it ideal for development, testing, and single-host deployments, but it doesn't provide orchestration features like automatic scheduling, self-healing, or multi-node management.

---

A Simple docker-compose.yml

services:
  web:
    build: .
    ports:
      - "8080:80"
    environment:
      - DB_HOST=db
    depends_on:
      - db

  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:alpine

volumes:
  postgres_data:

---

YAML Quick Reference

Key	Purpose
services	Defines containers (web, db, redis)
build	Builds an image from a Dockerfile
image	Uses an existing image from a registry
ports	Maps host ports to container ports
environment	Sets environment variables
depends_on	Controls startup order
volumes	Stores persistent data

---

What Happens When You Run docker compose up?

docker-compose.yml
        ↓
Compose reads the YAML
        ↓
Creates networks
        ↓
Creates volumes
        ↓
Builds images (if needed)
        ↓
Starts containers
        ↓
Application is running

One command replaces many manual docker run commands.

---

Modern Compose Features

1. Profiles

Profiles let you enable optional services only when needed.

For example, if your Compose file has a service assigned to the cache profile:

redis:
  image: redis:alpine
  profiles:
    - cache

You can start it with:

docker compose --profile cache up

Useful for:

• Development-only services
• Optional tools
• Testing environments

---

2. Watch (Compose V2)

develop:
  watch:
    - action: sync
      path: ./src
      target: /app/src

Run:

docker compose watch

Compose automatically syncs file changes without rebuilding the container.

(Available in recent Docker Compose V2 releases.)

---

The Biggest Gotcha

Many beginners believe this:

depends_on:
  - db

means

"The database is ready."

It doesn't.

It only means

"The database container has started."

The application inside may still be initializing.

A better approach is to combine startup ordering with health checks or design your application to retry connections until dependencies are available.

---

Common Expectations vs Reality

Expectation	Reality
Compose is a production orchestrator	It's primarily a development and single-host deployment tool
depends_on waits for the application	It only waits for the container to start
Automatic scaling	Manual
Self-healing	Not provided
Multi-node orchestration	Not supported
Hot reload	Supported with docker compose watch (Compose V2)

---

Simple Mental Model

Think of Docker Compose as a project manager.

Instead of starting every container one by one, Compose reads a blueprint and launches everything in the correct configuration.

It doesn't replace Docker.

It simply coordinates Docker for you.

---

Summary

In this guide you learned:

• Why Docker Compose exists
• What Compose actually is
• Compose V2 vs the old Compose V1
• Understanding services, build, image, ports, environment, depends_on, profiles, networks, and volumes
• What happens during docker compose up
• Modern features like Profiles and Watch
• Common misconceptions about Compose

---

Why This Matters

Docker Compose is one of the most valuable tools for local development.

It lets developers spin up complete applications with a single command, making multi-container development simple and repeatable.

As applications grow across multiple servers and require features like automatic scaling, self-healing, and high availability, orchestration platforms such as Kubernetes become the next step.

---

Question for You

What's the biggest misconception you had about Docker Compose?

Or what's one feature you wish you had discovered sooner?

---