Skip to content

What is docker-compose

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

Compose works in all environments: production, staging, development, testing, as well as CI workflows. You can learn more about each case in Common Use Cases.

Technically everything that you can do with docker-compose you could also do it with docker commands, but it would be rather tedious and prone to error.

Docker Compose is a great tool to quickly deploy and scrap containers, the compose file can run seamlessly on any machine installed with docker-compose.

Essentially, what Docker Compose is, is a recipe card — it’s a recipe of services that make up an application and the docker-compose.yml dictates how the services are mixed together.

Quote

Docker-Compose defines a complete system where services can communicate with each other on an isolated network, interacting with external resources as defined by the user.

Features

Compose provide the flexibility to use a project name to isolate the environments from each other, the project name is the base name of the directory that contains the project.

By default Compose sets up a single network for your app. Each container for a service joins the default network and is both reachable by other containers on that network, and discoverable by them at a hostname identical to the container name.

Compose preserves all volumes used by the services defined in the compose file, thus no data is lost when the containers are recreated using docker-compose up. Another cool feature is that only the containers which have changed are recreated, the containers whose state did not change remain untouched.

Another cool feature is the support for variables in the compose file, we can define variables in a .env file and use them in the docker-compose file.

Installation

Installation for Ubuntu is a simple process of executing just two commands. Full documentation for other platforms at: https://docs.docker.com/compose/install/

  1. Run this command to download the current stable release of Docker Compose: 

    sudo curl -L "https://github.com/docker/compose/releases/download/1.28.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

  2. Apply executable permissions to the binary: 

    sudo chmod +x /usr/local/bin/docker-compose

YAML

A docker-compose.yml looks like this: 

version: '3'

services:
  web:
    build: .
    ports:
    - "5000:5000"
    volumes:
    - .:/code
    - logvolume01:/var/log
    links:
    - redis
  redis:
    image: redis
volumes:
  logvolume01: {}

For more information about the docker-compose.yaml file, see the Compose file reference.

Tip

You can check the validity of the yaml file by running: docker-compose config

Configuration

Using Compose is basically a three-step process:

  1. Define your app’s environment with a Dockerfile so it can be reproduced anywhere.
  2. Define the services that make up your app in docker-compose.yml so they can be run together in an isolated environment.
  3. Run docker-compose up and Compose starts and runs your entire app.

detached mode (-d, --detach)

Detached mode shown by -d or — detach means a docker container is running in the background of your terminal. It doesn’t receive input or display any output.

Docker Compose Commands

  • docker-compose ps — lists all the services in a network. This is especially helpful when troubleshooting a service as it will give you the container ID and you can then run docker -it exec bash to enter the container and debug as needed.
  • docker-compose build — generates any needed images from custom Dockerfiles. It will not pull images from the Docker hub, only generate custom images.
  • docker-compose up — brings up the network for the services to run in
  • docker-compose stop — stops the network and saves the state of all the services
  • docker-compose start — restarts the services and brings them back up with the state they had when they were stopped
  • docker-compose down — burns the entire Docker network with fire. The network and all the services contained within are totally destroyed.

Further reading