Introduction

Docker Compose is a tool that allows you to define and manage multi-container Docker applications using a single configuration file.

Instead of running multiple Docker commands manually, Docker Compose enables you to define services, networks, volumes, and application configurations in a single YAML file and manage the entire application stack with simple commands.

Docker Compose is commonly used for:

Microservices Applications
Local Development Environments
Integration Testing
CI/CD Pipelines
Full-Stack Applications

Docker vs Docker Compose

Docker

Docker manages individual containers.

Characteristics:

Manages individual containers
Uses docker commands
Suitable for single-container applications

Example:

docker run -d -p 8080:80 nginx

Docker Compose

Docker Compose manages multiple containers together.

Characteristics:

Manages multiple containers
Uses a docker-compose.yml file
Suitable for multi-container and microservices applications
Simplifies networking and service management

Example:

docker compose up -d

Docker Compose simplifies the management of applications that consist of multiple services.

Why Docker Compose?

Consider an application consisting of:

Spring Boot Application
PostgreSQL Database
Redis Cache
Kafka Broker

Without Docker Compose, each service must be created and managed individually.

Docker Compose allows all services to be defined in a single file and started with a single command.

Benefits:

Simplified Multi-Container Management
Faster Environment Setup
Consistent Deployments
Built-in Networking
Service Dependency Management
Improved Developer Productivity

Docker Compose Architecture

    docker-compose.yml
                |
               ▼
      Docker Compose
                |
 ┌──────┼──────┐
 ▼           ▼            ▼
 App   Database    Redis
               |
              ▼
    Docker Network

Docker Compose automatically creates and manages:

Containers
Networks
Volumes

for all configured services.

Docker Compose File Structure

Docker Compose uses a YAML file named:

docker-compose.yml

Example:

services:
  web:
    image: nginx
    ports:
      - "80:80"

  mydb:
    image: postgres
    environment:
      POSTGRES_PASSWORD: test123

Compose File Components

Element	Description
services	Defines application containers
image	Docker image used to create containers
build	Builds a custom image using a Dockerfile
ports	Maps host ports to container ports
environment	Defines environment variables
volumes	Persistent storage configuration
networks	Communication layer between services

Note: Modern Docker Compose V2 no longer requires the version field, although it is still commonly seen in examples.

Example Docker Compose Configuration

services:

  web:
    image: nginx
    ports:
      - "80:80"

  mydb:
    image: postgres
    environment:
      POSTGRES_PASSWORD: test123

This configuration creates:

Nginx Web Server
PostgreSQL Database

and starts them together.

Docker Compose Networking

Docker Compose automatically creates a network and connects all services to it.

Example:

services:

  app:
    image: my-app

  mydb:
    image: postgres

The application can connect to the database using:

mydb:5432

Benefits:

Automatic Service Discovery
No Manual IP Management
Secure Communication Between Containers

Docker Volumes in Compose

Volumes provide persistent storage independent of the container lifecycle.

Example:

services:

  mydb:
    image: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Benefits:

Persistent Data
Easy Backup
Data Sharing
Database Storage

Environment Variables

Environment variables can be defined directly.

environment:
  DB_HOST: mydb
  DB_PORT: 5432

Or loaded from a .env file.

Example:

DB_HOST=mydb
DB_PORT=5432

Usage:

environment:
  DB_HOST: ${DB_HOST}
  DB_PORT: ${DB_PORT}

Image vs Build

Docker Compose supports both prebuilt images and custom image builds.

Using a Prebuilt Image

services:
  nginx:
    image: nginx

Docker pulls the image from Docker Hub.

Building a Custom Image

services:
  web:
    build: .

Docker builds an image using the Dockerfile located in the current directory.

Building Images with Docker Compose

Instead of pulling a prebuilt image, Docker Compose can build a custom image using a Dockerfile.

Step 1: Create Project Directory

mkdir my-workspace
cd my-workspace

Step 2: Create index.html

<html>
<body>
Hello, Docker Compose!
</body>
</html>

Step 3: Create Dockerfile

FROM nginx:alpine

COPY index.html /usr/share/nginx/html/index.html

Step 4: Create docker-compose.yml

services:
  web:
    build: .
    ports:
      - "8000:80"

Here Docker Compose builds an image using the Dockerfile in the current directory.

Step 5: Build Image

docker compose build

Step 6: Start Container

docker compose up

Access the application:

http://localhost:8000

Docker Compose only builds services configured with the build directive. Services using the image directive pull prebuilt images from a registry and are not built locally.

Docker Compose Commands Cheat Sheet

Create and Run Services Commands

docker compose up

Creates and starts all services defined in the compose file.

docker compose up -d

Creates and starts all services in detached mode.

docker compose -f docker-compose.prod.yml up

Creates and starts services using a custom compose file.

Stop and Remove Services Commands

docker compose down

Stops and removes containers, networks, and Compose resources.

docker compose stop

Stops all running services without removing them.

docker compose stop mydb

Stops a specific service.

docker compose kill

Forcefully stops all running services.

docker compose rm

Removes stopped service containers.

Start and Restart Services Commands

docker compose start

Starts previously stopped services.

docker compose restart

Restarts all services.

docker compose restart mydb

Restarts a specific service.

Image Management Commands

docker compose build

Builds or rebuilds images defined using the build directive.

docker compose pull

Downloads service images from a registry.

docker compose push

Pushes service images to a registry.

docker compose images

Lists images used by Compose services.

Logs and Monitoring Commands

docker compose logs

Displays logs from all services.

docker compose logs -f

Displays and follows logs in real time.

docker compose ps

Lists Compose-managed containers and their status.

Execute Commands

docker compose exec web ls /

Executes a command inside a running service.

docker compose exec web sh

Opens an interactive shell inside a service container.

Scaling Services Commands

docker compose up --scale mydb=3

Creates multiple instances of a service.

Pause and Resume Services Commands

docker compose pause

Pauses all running services.

docker compose unpause

Resumes paused services.

Configuration Management Commands

docker compose config

Validates and displays the fully resolved Compose configuration.

docker compose --help

Displays all available Docker Compose commands.

Verify Installation Command

docker compose version

Displays the installed Docker Compose version.

Note:

Modern Docker installations use Docker Compose V2, which uses command: docker compose

instead of the older command: docker-compose

Both may still work depending on your Docker installation.

Common Use Cases

Microservices Applications

Manage multiple services such as:

API Gateway
User Service
Order Service
Database
Redis
Kafka

using a single Compose file.

Local Development

Create development environments that closely match production.

Integration Testing

Run databases, caches, and application services together for testing.

CI/CD Pipelines

Create temporary environments for automated builds and tests.

Full-Stack Applications

Run frontend, backend, database, cache, and messaging services together.

Docker Compose Best Practices

Use Specific Image Versions

Preferred:

image: postgres:16

Avoid:

image: latest

Use Environment Variables

Keep configuration outside source code.

Use Named Volumes

Store persistent data outside containers.

Use Restart Policies

restart: unless-stopped

Automatically restart containers after failures or system reboots.

Use Health Checks

Ensure dependent services become healthy before application startup.

Keep Compose Files Simple

Separate development and production configurations when required.

Conclusion

Docker Compose simplifies the management of multi-container applications by allowing services, networks, volumes, and configurations to be defined in a single YAML file.

In this guide, we covered:

Docker Compose Fundamentals
Docker vs Docker Compose
Compose File Structure
Networking
Volumes
Environment Variables
Image Building
Docker Compose Commands
Common Use Cases
Best Practices

Docker Compose is an essential tool for developers and DevOps engineers who need a simple and efficient way to manage complete application stacks during development, testing, and deployment.