Docker Compose Tutorial: What It Is, Examples & How It Works

Modern applications seldom consist of a single process. Even a basic web application relies on several services: web servers, databases, caches, background workers, and message queues. Handling these components separately using basic Docker commands is prone to errors and hard to maintain.

This is where Docker Compose comes in.

Docker Compose enables developers to manage multiple container applications with a single configuration file and a handful of commands. Instead of manually creating containers, setting up networks, and mounting volumes, everything is defined in a single place.

What this tutorial covers:

• What Docker Compose is and how it works
• Key components such as services, networks, and volumes
• Practical Docker Compose examples
• Best practices and common pitfalls
• The role of Docker Compose in modern DevOps (2026)

So, let’s get started.

What is Docker Compose?

Docker Compose is a utility for defining, configuring, and running multi-container Docker applications. Docker Compose uses a YAML file (docker-compose.yml) to define application services, their dependencies, networks, and storage.

Single-host container orchestration explained.

Docker Compose is designed for a single host machine. Unlike Kubernetes, it is intended for:

• Local development
• Test environments
• Small- to medium-sized deployments
• When Docker Compose is used in real projects

When Docker Compose is used in real projects

• Local development environment
• Integration testing
• CI/CD pipelines
• Proof-of-concept and staging environments
• Small-scale production environments

Core Components of Docker Compose

docker-compose.yml

Purpose of the Compose file

The docker-compose.yml file contains the following information:

• Services
• Images or build specifications
• Ports
• Volumes
• Networks
• Environment variables

It serves as the central source of truth for your application stack.

Why YAML is used

YAML is a human-readable, structured, and declarative language, making it the best choice for infrastructure configuration.

Services

What a service is

A service is a single container configuration. Each service launches a container from an image or Dockerfile.

One service vs multiple services

• Single-service Compose files are good for simple apps.
• Multi-service configurations are typical for real-world applications (apps, databases, caches).

Networks

Default networks

Docker Compose will automatically create a default bridge network for all services in a project.

Service-to-service communication

Services can communicate with each other using service names and hostnames, without needing to specify ports.

Volumes

Persistent data handling

Volumes are used to handle data outside the lifetime of containers so that data isn’t lost when containers are restarted.

Named vs anonymous volumes

• Named volumes: reusable and explicitly managed
• Anonymous volumes: auto-generated and more difficult to manage.

Environment Variables

Inline variables

Variables can be defined inline in the docker-compose.yml file.

.env file usage

The .env file is used to provide a secure way to configure your application without hardcoding values.

Projects

What a Docker Compose project is

A project is a collection of containers, networks, and volumes launched from a Compose file.

Project name and isolation

Each project is isolated by name so that there are no conflicts when running multiple stacks.

Why Use Docker Compose?

• Enhances and streamlines multi-container development.
• Guarantee consistency across environment deployments
• Facilitates faster developer onboarding
• Helps reduce the number of command-line inputs and the complexity of commands
• Provides a superior user experience when compared to using the native Docker CLI

How Does Docker Compose Work?

• Read the Compose file (docker-compose.yml).
• If needed, builds images.
• Creates and configures networks and volumes.
• Starts containers in the correct order.
• Manages the application’s life cycle.

All the above actions can be performed with a single command.

Is Docker Compose Still Relevant?

Docker Compose in modern DevOps.

Yes, Docker Compose is still an essential part of:

• Local development
• CI pipelines
• Small deployments

Docker Compose vs Kubernetes (when to use each)

• Docker Compose: simplicity, speed, local-first
• Kubernetes: scalability, resilience, cluster orchestration

Real-world relevance in 2026

Docker Compose is still widely used and supported, especially for development.

Docker vs Docker Compose

Core differences explained

• Docker is for single containers.
• Docker Compose is for multiple containers.

Use cases for each

• Docker: simple apps with one container
• Docker Compose: networked services

When Docker Compose is the better choice

Anytime your app depends on more than one thing. Docker Compose is the winner.

Docker Compose Benefits

• Declarative config
• Single command to start
• Networking out of the box
• Teardown and rebuild made easy
• CI/CD ready

Step-by-Step Docker Compose Tutorial

Check if Docker Compose Is Installed

docker compose version

If installed, you’ll see the version number.
If not, install Docker Desktop or Docker Compose manually.

Create Your Application

Example project structure:

my-app/
├── docker-compose.yml
├── app/
│   └── index.js
└── Dockerfile

This structure helps your services be organised and easy to maintain.

Create a Docker Compose File

Example docker-compose.yml:

version: "3.9"

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

This defines:

• One service (web)
• Uses the Nginx image
• Exposes port 8080

Bring Up Your Containers

docker compose up

Run in detached mode:

docker compose up -d

Docker Compose will pull the images, create the networks, and start the containers.

Manage Your Docker Compose Stack (Commands)

Common commands:

docker compose ps
docker compose logs
docker compose restart
docker compose stop
docker compose down
docker compose down

Deletes containers and networks (and optionally volumes).

Use Docker Compose Profiles

Profiles enable the ability to turn the service on or off depending on the environment.

Examples include:

• Dev vs production
• Optional monitoring services
• Feature-based stacks

Understand Docker Compose Projects

The project name defaults to the directory name.

Override it:

docker compose -p myproject up

This enables multiple isolated stacks on a single host.

Set Docker Compose Environment Variables

Using .env file:

DB_HOST=database
DB_PORT=5432

In docker-compose.yml:

environment:
  - DB_HOST=${DB_HOST}

Environment variables improve security and flexibility.

Control Service Startup Order

Docker Compose supports dependencies:

depends_on:
  - db

For production, combine this with health checks.

Docker Compose Examples

Example 1: Web Application + Database (Node.js + PostgreSQL)

version: "3.9"

services:
  app:
    image: node:18
    container_name: node_app
    working_dir: /usr/src/app
    volumes:
      - ./app:/usr/src/app
    command: npm start
    ports:
      - "3000:3000"
    depends_on:
      - db

  db:
    image: postgres:15
    container_name: postgres_db
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

What’s happening in this example?

• Two services are defined: app and db
• A shared network is automatically created by Docker Compose
• The app service connects to PostgreSQL on the hostname db
• Data is persisted in the database using a named volume

Great for backend development and testing.

Example 2: Nginx Reverse Proxy + Backend Service

Internal networking allows systems to be connected without exposing their backend publicly; instead, they’re managed through nginx to route requests to other backends.

version: "3.9"

services:
  backend:
    image: node:18
    container_name: backend_service
    ports:
      - "4000"

  nginx:
    image: nginx: latest
    container_name: nginx_proxy
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - backend

This architecture is a good fit for any API-based application.

Example 3: Production-Ready Docker Compose Setup

version: "3.9"

services:
  web:
    image: nginx: latest
    restart: always
    ports:
      - "80:80"
    deploy:
      resources:
        limits:
          memory: 512M

  api:
    image: my-api: latest
    restart: unless-stopped
    environment:
      APP_ENV: production

Best practices that can be used in this setup include:

• Restart policies
• Resource limits
• Environment-based configurations

For small and medium production infrastructure only.

Docker Compose Commands Cheat Sheet

Best Practices for Docker Compose

• Utilise .env files
• Avoid hardcoding credentials
• Design files in a modular form
• Keep configurations for different environments (development vs production) separated.
• Don’t rely heavily on Compose for orchestration.

Common Challenges and Mistakes

• The application fails, but containers do start
• Conflicts occur with ports
• Data is not saved correctly, leading to data loss
• Inaccurate assumptions/understandings of networking and/or how to use it.

Key Points

• Docker Compose allows you to create applications using multiple containers.
• The best use case for Docker Compose is during development and small-scale deployments.
• Uses YAML files to create an application that can be repeated multiple times.
• It is still a very popular method of building applications today.

Frequently Asked Questions

Conclusion

For anyone developing containerised applications, Docker Compose is an important tool. It is the in-between of basic Docker usage and a full orchestration platform.

If you work with multi-service applications, Docker Compose isn’t just a nice-to-have; it’s essential.

After this, continue to learn Docker networking and optimise Docker files, and look to learn about Kubernetes at some point as a primary orchestration platform.

Shivam Mahajan

Shivam Mahajan is an editor skilled in SysOps, Tech, and Cloud. With experience at AttuneOps and other companies, he simplifies complex technical material for easy understanding.