Introduction

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file (typically named docker-compose.yml) to configure your application’s services, networks, and volumes. Then, with a single command, you create and start all the services defined in your configuration.

Docker Compose is ideal for:

  • Development environments
  • Automated testing environments
  • Single host deployments
  • CI/CD workflows

Using Docker Compose involves a three-step process:

  1. Define your application’s environment in a Dockerfile
  2. Define the services that make up your application in a docker-compose.yml file
  3. Run docker compose up to start and run your entire application

Usage

Installation

Before using Docker Compose, make sure you have Docker installed and the Docker engine running on your system.

To install Docker Compose:

1
2

sudo apt-get update
sudo apt-get install docker-compose-plugin

Creating a docker-compose.yml file

Here’s a basic example of a docker-compose.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

version: "3"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./website:/usr/share/nginx/html
  db:
    image: postgres:13
    environment:
      POSTGRES_PASSWORD: example
      POSTGRES_USER: user
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

This configuration sets up two services:

  • A web server using the nginx:alpine image
  • A database using the postgres:13 image

Basic Commands

Start your services 

1

docker compose up

Add -d to run in detached mode (background):

1

docker compose up -d

Stop your services 

1

docker compose down

To remove volumes as well:

1

docker compose down -v

View running services 

1

docker compose ps

View logs 

1

docker compose logs

Follow logs with:

1

docker compose logs -f

Execute commands in a service container 

1

docker compose exec web sh

Scaling Services

You can run multiple instances of a service:

1

docker compose up -d --scale web=3

This starts 3 instances of the web service.

Environment Variables

You can use environment variables in your docker-compose.yml:

1
2
3
4
5

services:
  web:
    image: nginx:alpine
    ports:
      - "${NGINX_PORT}:80"

Create a .env file in the same directory:

NGINX_PORT=8080

Working with Networks

Docker Compose automatically creates a network for your application. You can also define custom networks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

services:
  web:
    networks:
      - frontend
  db:
    networks:
      - backend
      - frontend

networks:
  frontend:
  backend:

Depends On

Specify dependencies between services:

1
2
3
4
5
6
7
8
9

services:
  web:
    depends_on:
      - db
      - redis
  db:
    image: postgres
  redis:
    image: redis

Health Checks

Add health checks to ensure services are properly started:

1
2
3
4
5
6
7
8

services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 1m30s
      timeout: 10s
      retries: 3
      start_period: 40s

Example: Full-Stack Web Application

Here’s a more complete example for a web application with frontend, backend, and database:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

version: "3"

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend
    environment:
      - API_URL=http://backend:8000

  backend:
    build: ./backend
    ports:
      - "8000:8000"
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgres://user:password@db:5432/mydb
      - NODE_ENV=development

  db:
    image: postgres:13
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb

volumes:
  postgres_data:

This setup demonstrates how Docker Compose can orchestrate a complete application stack with multiple interconnected services.

Resources

Edit this page

Last updated 04 May 2025, 18:44 CEST. history