What is Docker Compose?

Imagine you’re a chef, and you’ve perfected a complex dinner party menu.

You have:

• An appetizer recipe
• A main course recipe
• Two side dish recipes
• A dessert recipe

Each recipe is on its own card. Each card says:

• Ingredients needed
• Cooking temperature
• Time required
• When to start (dessert needs to chill for 2 hours, so start it first)

Now, you could cook each dish separately, reading each recipe card individually, keeping track of timing in your head. That works, but it’s mentally taxing.

Instead, you create a master menu card that references all the recipes:

DINNER PARTY MENU
├─ Start at 4:00 PM
│  └─ Dessert (needs 2h chilling)
├─ Start at 5:30 PM
│  └─ Side Dish 1 (needs 1h baking)
├─ Start at 6:00 PM
│  ├─ Main Course (45min)
│  └─ Side Dish 2 (30min)
└─ Start at 6:40 PM
   └─ Appetizer (serve fresh)

This master card doesn’t contain the full recipes—it references them. It describes:

• What dishes you’re making
• What order to cook them
• How they relate to each other

Docker Compose is the master menu card for your containerized application.

Each service (container) is like a recipe card (Dockerfile/image). The docker-compose.yml file is the master menu that describes:

• What services you’re running
• How they connect
• What order to start them
• How they depend on each other

Docker Compose is a tool for defining and running multi-container applications.

Let’s break that down:

1. It’s a CLI tool

Docker Compose used to be a separate binary called docker-compose (with a hyphen). You installed it separately.

docker-compose --version
# docker-compose version 1.29.2

As of Docker v2 (released 2020+), Compose has been integrated as a Docker CLI plugin. Now you use:

docker compose version
# Docker Compose version v2.24.0

Same tool, different invocation. Most documentation uses the newer docker compose (space) syntax, but docker-compose (hyphen) still works if you have v1 installed.

2. It reads a YAML file

By default, Compose looks for a file called docker-compose.yml (or docker-compose.yaml) in the current directory.

This file uses YAML syntax to declare:

• Services (containers)
• Networks
• Volumes
• Configs
• Secrets

3. It’s a wrapper around Docker commands

Compose doesn’t create its own containers. It uses the Docker Engine API to create containers, networks, and volumes—the same API that docker run, docker network create, etc. use.

When you run docker compose up, Compose:

• Parses the YAML file
• Translates it into Docker API calls
• Calls the Docker daemon to create resources

4. It tracks state

Compose remembers what it created. When you run docker compose down, it knows which containers, networks, and volumes belong to this project and removes them.

5. It’s project-scoped

By default, Compose uses the directory name as the project name. All resources get prefixed with this project name.

If you’re in /home/learner/blog and run docker compose up, Compose creates:

• blog-db-1 (container)
• blog-app-1 (container)
• blog_default (network, if not specified)
• blog_db-data (volume)

This allows multiple compose projects to run on the same host without name conflicts.

This often confuses people, so let’s clarify:

Docker Engine = The core container runtime. Runs on a single host. Manages containers, images, networks, volumes.

Docker Compose = An orchestration tool for multi-container apps on a single host. It makes complex applications easier to define and manage.

Docker Swarm = A production-grade orchestrator for multi-container apps across multiple hosts. Built into Docker Engine. Cluster management, service scaling, load balancing.

Kubernetes = A powerful, production-grade orchestrator for containerized apps across clusters. Not Docker-specific. Industry standard for large-scale deployments.

When to use what:

Tool	Use Case
docker run	Single container, quick tests
Docker Compose	Multi-container apps, development, small production (single host)
Docker Swarm	Production orchestration, multiple hosts, simpler than K8s
Kubernetes	Large-scale production, complex applications, enterprise-grade orchestration

Compose is not a replacement for Kubernetes. Compose is for single-host scenarios. Kubernetes is for cluster scenarios.

But for local development, Compose is perfect. Even if you deploy to Kubernetes in production, you’ll often use Compose locally.

Docker Compose has evolved. The compose file format has versions.

When you see:

version: '3.9'

This declares which compose file specification you’re using.

Key versions:

• v1 (legacy): Original format. Don’t use.
• v2: Introduced services, networks, volumes sections. Still used, but deprecated.
• v3: Designed to work with Docker Swarm. Most common today.
  • v3.0 to v3.9: Incremental features added.
• v3.9: Latest v3 version. Recommended for most use cases.
• Compose Specification (no version field): New standard. Future-proof. Decoupled from Docker versions.

What should you use?

For new projects, use version: '3.9' or omit the version field entirely (uses the Compose Specification).

# Modern approach (no version field)
services:
  web:
    image: nginx

Or:

# Explicit version
version: '3.9'
services:
  web:
    image: nginx

VS Code Integration:

VS Code has excellent Docker and Compose support:

• YAML validation for docker-compose.yml
• IntelliSense for service properties
• Right-click to start/stop services
• View logs directly in the IDE

JetBrains IDEs (PyCharm, WebStorm, IntelliJ):

• Docker Compose run configurations
• Debug containers directly
• View service status in Services panel

GitHub Actions:

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start services
        run: docker compose up -d
      - name: Run tests
        run: docker compose exec -T app pytest
      - name: Cleanup
        run: docker compose down

CI/CD Pipelines:

Most CI/CD systems (GitLab CI, CircleCI, Jenkins) support Docker Compose for spinning up test environments.

---