What is Docker Compose, and how to use it

Docker Compose is a tool designed for defining and running multi-container projects. Developers use it to simplify the management of interconnected services, such as combining a front-end application and a database server, allowing them to administer the entire application stack easily.

By using a single YAML file, Docker Compose enables developers to specify the necessary infrastructure for building an application, including the image to use, the internal network setup, and the persistent volume to mount. Then, you can build all the containers based on the configuration by running the docker compose up command.

Throughout the project lifecycle, you can manage containers using other Compose commands. For example, docker compose down tears down all the services, while docker compose ps lists currently running containers specified within the YAML file.

To use Docker Compose, you must have Docker Engine and Docker CLI installed. Then, configure it by downloading the plugin using your system’s package manager or Homebrew. If you use Docker Desktop, this orchestration tool is pre-packaged out of the box.

Dive deeper to learn more about what Docker Compose is and how to use it to manage multi-container applications.

What is Docker Compose?

Docker Compose is a tool that enables developers to easily define and run multi-container Docker applications. Its primary purpose is to simplify, centralize, and unify the management of multiple services.

Docker Compose relies on a single YAML file where you define everything about the containers in your application: which image each service should use, how they communicate, and where they store persistent data. This configuration enables you to build and manage these containers.

How does Docker Compose work?

Docker Compose works by defining three core components of multi-container applications in the YAML file: services, networks, and volumes.

When you deploy an app from the YAML file, Docker Compose will pull or build the image to create that service, also known as a container.

Docker Compose then creates an internal network to enable services to communicate with one another and initializes volumes to store persistent data that the containers can share. It also sets up the environment variables for each service to pass data without directly hardcoding them into its image.

All configurations – including which image to use, how to set up the network, where to mount the persistent volumes, and which environment variables to include – are defined in the YAML file. This means you can build and manage all containers of your application from this file.

Example of a Docker Compose YAML file

Here’s an example of an actual Docker Compose YAML file defining a project comprising two interconnected services: a simple web application and a Redis cache instance.

To help you understand the configuration, check the comments to see what each line does.

services:

  web: # Service for the web application

    build: . # Builds the image from the Dockerfile in the current directory

    ports:

      - "8000:5000" # Maps host port 8000 to container port 5000

    depends_on:

      - redis # Ensures 'redis' starts before 'web' 

    volumes:

      - ./:/app # Mounts the current directory into the container at /app (bind mount)

    environment:

      REDIS_HOST: ${REDIS_HOST:-redis} # Sets REDIS_HOST from env or defaults to 'redis'

  redis: # Service for the Redis cache

    image: redis:6 # Uses the official Redis image (version 6)

    expose:

      - "6379" # Exposes port 6379 to other services within the Docker network

    volumes:

      - redis_data:/data # Persists Redis data in a named volume

volumes:

  redis_data: {} # Declares the named volume for Redis data persistence

Note that depending on your application, services, and configuration, the exact content of the YAML file varies.

How to install Docker Compose

The steps to install Docker Compose will vary depending on the type of Docker application and your operating system.

If you use Docker Desktop, Compose is already pre-configured. For Docker CLI, you can set up the Compose plugin either from the official repository or by downloading it manually. We’ll explain how to do it from the official repository, as this will simplify future updates.

Before proceeding, ensure that you’ve configured Docker Engine and Docker CLI. If you haven’t, check out our guide to installing Docker on Ubuntu to learn more about the steps.

Once you have Engine and CLI set up, install Compose based on your operating system. In Linux, you can do this using your system’s package manager. For example, here are the commands for doing it on Debian-based distributions:

sudo apt update

sudo apt install docker-compose-plugin

If you use non-Debian operating systems, simply replace apt with the corresponding package manager. For instance, use dnf if you run RHEL-based distros.

For macOS users, install Docker Compose via Homebrew using this command:

brew install docker-compose

On both Linux and macOS, you can check if Docker Compose is successfully installed by running the following command:

docker compose version

If Docker Compose is properly configured, you will see its version number on your terminal.

How to use Docker Compose

Using Docker Compose enables you to define your application configuration, run the stack, and manage its lifecycle with a single tool.

To better illustrate how to use Docker Compose in real-world scenarios, let’s say we want to run WordPress on Ubuntu using Docker. Here’s how the workflow looks.

1. Use a text editor like nano to create a YAML or YML configuration file. You can use any name, but it’s advised to use the default docker-compose.yml or compose.yaml name for easier management.
2. Within the YAML file, specify the WordPress and MySQL images, along with their settings, like network setup, persistent volume, and dependencies.
3. Use Docker Compose to build and run all the WordPress and MySQL services using the specified settings and dependencies from the YAML file:

docker compose up

4. Throughout your project, you will need to stop and tear down all your containers for updates or maintenance. To do it, run the following command:

docker compose down

You can modify the behavior of the docker compose command using flags. For example, if you wish to build an application from a configuration that doesn’t use the default name, add the -f or –file flag to specify the file Docker Engine will read:

docker compose -f your-compose-file.yaml up

By default, Docker Compose will build the containers in your current working directory. To deploy the application in another folder, add –project-directory and specify the deployment path:

docker compose --project-directory /full/deployment/path up

You can also combine multiple flags by separating them using a backslash. For example, use the following command if you want to deploy an application from a YAML file with a specific name to another directory:

docker compose \
  -f /path/to/my-docker-compose.yaml \
  --project-directory /path/to \
  up

When removing containers, the data remains intact because they are attached to persistent volumes. If you want to remove the volumes as well, use the –volumes flag like so:

docker compose down --volumes

Common Docker Compose commands

In addition to up and down, there are other Docker Compose commands used to manage the entire application stack. Some of the most used ones are:

• docker compose ps – lists the running containers managed by Docker Compose. The output includes the container name, image, command, service, status, and ports.
• docker compose logs – aggregates and displays logs from all services in the stack. Adding the -f flag outputs logs from all containers in real time.
• docker compose start – starts existing stopped containers.
• docker compose stop – stops running containers without removing or tearing them down.
• docker compose restart – forces an immediate restart of the containers.
• docker compose build – forces a rebuild of images that use the build directive inside the YAML file. You can add –no-cache flag to initiate a clean rebuild.
• docker compose push – pushes all built images to their remote registry URLs.
• docker compose pull – retrieves all images required to build the stack without starting containers.

What’s the difference between Docker vs. Docker Compose?

Docker has various concepts, terms, and tools, each of which serves distinct roles within the container ecosystem. Understanding them allows you to use the platform efficiently and effectively.

Compose is part of a broader Docker ecosystem and is often confused with the Docker CLI. They are both command-line utilities that manage entities on Docker, but they differ in various aspects.

Here is a comparison between Docker Compose and Docker CLI.

Aspect	Docker CLI	Docker Compose
Use case	Best for single container setups	Built for multi-container apps
Orchestration	Manual, meaning you need to run each container individually	Automated, allowing you to manage all services via a single YAML file
Configuration format	Specified within the command using flags	Declared inside the YAML file
Reusability and portability	Sharing and reproducing complex setups are difficult because the config is specified within the command	Easily versioned and reused because you can build a project from a self-contained config file
Testing and development setup	Tedious for multi-service development environments	Ideal for local development because all services are contained in one file
Production usage	Suitable for the production of simple projects, but not for multi-service apps	It can be used for production environments, but it is commonly replaced by Docker Swarm or Kubernetes for larger-scale projects
Learning curve	Easier for beginners as it only manages a single-container app	Slightly steeper, but more applicable for real projects

What’s the next step after using Docker Compose?

Once you’ve learned how to work with Docker Compose, you can use it to manage your multi-service project seamlessly and efficiently. In a real-world scenario, however, you may need to work with individual containers for tasks such as adding a new service or troubleshooting a specific part of your application.

With that in mind, it’s essential to learn how to create a Docker container so you can work with the broader ecosystem more efficiently.

Note that while Docker Compose and containers are useful concepts of this containerization platform, you need to learn other tools as your project grows. For example, switch to Kubernetes or Docker Swarm to manage multiple containers more reliably.

If you wish to deploy a containerized application on Hostinger’s VPS hosting solution, you can use our Docker Compose Manager feature. This gives you a management dashboard built into hPanel to streamline the deployment and administration of Docker-based applications.

All of the tutorial content on this website is subject to Hostinger's rigorous editorial standards and values.