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

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

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?