Docker Compose

Docker Compose is one of the most useful tools in modern container-based development. It allows you to define, manage, and orchestrate multi-container applications using a single YAML file. This guide covers all the essentials you need to understand before you start building real-world Compose setups.

1. What is Docker Compose?

Docker Compose is a tool used to define and run multi-container Docker applications.
Instead of manually running each container with long docker run commands, you can describe your entire application stack (web server, database, cache, worker, etc.) inside a YAML file named:

docker-compose.yml

2. Why Do We Use Docker Compose? (Purpose)

2.1 Multi-Container Application Management

Most applications today have multiple components:

• API/Application server

• Database

• Redis / RabbitMQ

• Worker services

Compose makes them all run together, networked and configured automatically.

2.2 Configuration as Code

Ports, volumes, environment variables, networks—everything is declared in one YAML file.
You can version-control it, share it, and recreate the exact setup anytime.

---

2.3 Consistency Across Developers

The entire team runs the same environment:

docker compose up

No more “works on my machine” problems.

---

2.4 Repeatability & Automation

Startup, shutdown, scaling, logs—everything is handled with simple commands.

---

3. Core Concepts of Docker Compose

3.1 Services

Each container you define is a service.
Example:

• web

• db

• redis

---

3.2 Images

A service uses a Docker image:

• Pre-built image from Docker Hub

• Or via a local Dockerfile using build:

---

3.3 Volumes

Volumes store data persistently—even if containers are removed.

Example:

volumes:

  - db_data:/var/lib/postgresql/data

3.4 Networks

Compose creates a private network.
Services communicate using service names:

web → db:5432

3.5 Environment Variables

You can pass variables directly or through an .env file.

---

3.6 depends_on

Controls startup order. Example:

depends_on:

  - db

4. Sample docker-compose.yml File

Below is a common web + PostgreSQL setup:

services:

  web:

    build: ./app

    ports:

      - "8000:8000"

    environment:

      - DB_HOST=db

    depends_on:

      - db

  db:

    image: postgres:16

    environment:

      - POSTGRES_USER=myuser

      - POSTGRES_PASSWORD=secret

      - POSTGRES_DB=mydb

    volumes:

      - db_data:/var/lib/postgresql/data

volumes:

  db_data:

This file:

• Builds & runs the app

• Runs Postgres

• Automatically networks both

• Persists DB data using db_data volume

5. docker compose vs docker-compose

Historically, Docker Compose was a separate binary:

docker-compose up

Now it is integrated into Docker CLI:

docker compose up

The space-variant is the modern and recommended approach.

6. Essential Docker Compose Commands

6.1 Start/Stop

Start all services with logs:

docker compose up

Start in background:

docker compose up -d

Stop and remove containers:

docker compose down

Stop + remove volumes:

docker compose down -v

6.2 Status & Logs

Check running services:

docker compose ps

Live logs:

docker compose logs -f

Logs for specific service:

docker compose logs -f web

6.3 Build Operations

Build images:

docker compose build

Build without cache:

docker compose build --no-cache

Pull images:

docker compose pull

6.4 Execute Commands Inside Containers

Open interactive shell:

docker compose exec web bash

If bash not available:

docker compose exec web sh

Run one-off command:

docker compose run --rm web npm test

6.5 Scaling Services

Run multiple copies of the same service:

docker compose up --scale web=3 -d

7. Real-World Developer Workflow

1. Clone project

2. Set .env variables

3. Launch:

docker compose up -d

Check logs / debug

Stop:

docker compose down

This becomes your daily development workflow.

8. Additional Features (for Future Learning)

• Profiles – optional services

• Override Files – separate files for dev/qa/prod

• Healthchecks – control container readiness

• Secrets – secure values for production

9. Quick Recap

• Docker runs containers

• Docker Compose runs application stacks

• All config lives in docker-compose.yml

• Most important commands:

• docker compose up -d

• docker compose down

• docker compose ps

• docker compose logs -f

• docker compose exec