Skip to main content

Docker Compose

Docker Compose is a tool used for defining and running multi-container Docker applications. With Compose, you can define a multi-container application in a single YAML file, and then spin up all the services with a single command.

This guide explains the basics of Docker Compose, its key components, and how to use it effectively.

Table of Contents​

What is Docker Compose?​

Docker Compose allows you to define and manage multi-container Docker applications using a docker-compose.yml file. Each service within the file is defined as a separate container with its own configuration, and Compose ensures all services can communicate with each other.

Benefits of Docker Compose​

  • Multi-container management: Easily define and manage complex multi-container applications.
  • Automation: Automates container creation, starting, and stopping, making deployment easier.
  • Consistency: Define your entire application environment in one file for consistent deployments.
  • Networking: Compose automatically handles the networking between containers.

Installing Docker Compose​

Before using Docker Compose, you need to install it. You can install Docker Compose on Linux, Mac, and Windows. Here are the installation steps for Docker Compose:

On Linux​

# Download the latest version of Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r .tag_name)/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# Apply executable permissions
sudo chmod +x /usr/local/bin/docker-compose

On Windows & Mac​

You can download Docker Compose along with Docker Desktop from the official Docker website.

Docker Compose File Structure​

The Docker Compose file is written in YAML format and typically named docker-compose.yml. Below are the key sections of the docker-compose.yml file:

  • version: Specifies the version of the Compose file format.
  • services: Defines the containers in the application.
  • volumes: Used for defining persistent data storage.
  • networks: Defines custom networks for your services.
  • configs: Defines configuration data for services.

Example Structure​

version: "3.8"

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:latest
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Creating a Docker Compose File​

To create a Docker Compose file, follow these steps:

  1. Create a docker-compose.yml file in your project directory.
  2. Define your services (containers) under the services section.
  3. Specify any configuration, environment variables, volumes, and networks.

Example: Simple Web and Database Setup​

Here is an example of a basic docker-compose.yml file with a web server and a database:

version: "3.8"

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    networks:
      - mynetwork
  db:
    image: postgres:latest
    environment:
      POSTGRES_PASSWORD: password
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - mynetwork

networks:
  mynetwork:

volumes:
  db-data:

In this example:

  • The web service uses the nginx image and maps port 8080 on the host to port 80 inside the container.
  • The db service uses the postgres image and sets an environment variable for the database password.
  • Both services are connected to the same custom network (mynetwork), allowing them to communicate.

Starting the Application with Docker Compose​

Once the docker-compose.yml file is defined, you can use the following command to start the application:

docker-compose up
  • This command will build and start all the services defined in the docker-compose.yml file.
  • To run it in the background (detached mode), use the -d flag:
docker-compose up -d

To stop the application and remove containers, use:

docker-compose down

This command stops all the services and removes the containers, networks, and volumes defined in the docker-compose.yml file.

Managing Docker Compose Projects​

Docker Compose provides several commands to manage the lifecycle of a project:

  • Start services:

    docker-compose up

  • Stop services:

    docker-compose down

  • View logs:

    docker-compose logs

  • List services:

    docker-compose ps

Common Docker Compose Commands​

Here are some of the most commonly used Docker Compose commands:

CommandDescription
docker-compose upBuilds and starts containers in the background (detached mode).
docker-compose downStops and removes containers, networks, and volumes.
docker-compose buildBuilds or rebuilds the services defined in the Compose file.
docker-compose logsFetches logs for the services.
docker-compose psLists containers that are part of the Compose project.
docker-compose exec <service> <command>Executes a command inside a running service container.

Docker Compose Networks​

Docker Compose automatically creates a default network for the services to communicate. However, you can define custom networks in the docker-compose.yml file for more control over how services communicate.

Example of Custom Networks:​

version: "3.8"
services:
  web:
    image: nginx:latest
    networks:
      - frontend
  db:
    image: postgres:latest
    networks:
      - backend

networks:
  frontend:
  backend:

In this example:

  • The web service connects to the frontend network.
  • The db service connects to the backend network.
  • The services cannot communicate with each other unless explicitly connected to the same network.

Best Practices for Docker Compose​

  • Use .env Files: Store environment variables in .env files for better manageability and portability.
  • Version Control: Always keep the docker-compose.yml file under version control (e.g., Git) to track changes.
  • Minimal Service Definitions: Define only essential configurations in the docker-compose.yml file to keep it simple and readable.
  • Use Networks for Isolation: Create custom networks to isolate services and control communication between them.

Conclusion​

Docker Compose is a powerful tool for defining and running multi-container Docker applications. With Compose, you can easily manage complex applications, define services, and control their interaction. It is especially useful for local development, testing, and deploying multi-service applications.

For more details, check out the official Docker Compose documentation.