Docker Compose

There are two main ways in which people run Docker. The first way uses the docker command, which we covered in the previous section. In this section, we'll look at the second way, in which a configuration file is used to define the settings for our Docker container.

In this step of the guide, we will cover:

What are docker-compose files?

Why would we use configuration files when we can just use commands? Some Docker commands can get pretty long. Plus, if we want to run 7+ containers as part of one website, it can be a lot of work entering 7 docker run or docker rm commands every time you want to start/stop our websites.

docker-compose files are usually called docker-compose.yml. They are nothing more than text files, and they use a specific notation called yaml, which is like JSON, but more readable. docker-compose is also the name of the command we'll use to run Docker this way.

In this step of the guide, we won't cover everything you can do with docker-compose files (that would be a lot), but we will cover some basics, and show you how to use them to run containers.

Creating a docker-compose file

In this step, we'll set up a simple docker-compose file, that tells Docker how we want to run whoami.

Make a new directory, and in that directory, create a new file called docker-compose.yml. Using a text editor, enter the following contents into docker-compose.yml:

version: '3'

    image: containous/whoami
      - 80:80

Let's go over how this file works:

  • The line version: '3' tells Docker which version of docker-compose syntax to expect

  • services is the yaml section in which we list the applications we want to run

  • whoami is the name we have given to the service we want to run

  • image: containous/whoami tells Docker which image to use for the container

  • The lines ports: and - 80:80 tell Docker that we want port 80 on the outside of the container, to be mapped to port 80 on the inside of the container.

Notice that the syntax is similar to what we used in the docker run command in the Whoami section. That is of course intentional, and shows how Docker and docker-compose are closely related.

Running docker-compose

Running docker-compose is simple, since we already did the hard work in creating the configuration file. Docker assumes that a docker-compose file is called docker-compose.yml, so all we need to do, is run

docker-compose up

This gave the output

 ⠿ Container play-whoami-1  Created                                                                                                                                            0.1s
Attaching to play-whoami-1
play-whoami-1  | Starting up on port 80

The important line above is play-whoami-1 | Starting up on port 80. This tells us that the line Starting up on port 80 was logged from within a container called play-whoami-1.

Once again, let's use curl http://localhost:80 in a new terminal to check the container is running. This gives a similar output to when we ran whoami with docker.

Hostname: 268742d8d212
GET / HTTP/1.1
Host: localhost
User-Agent: curl/7.79.1
Accept: */*

Running docker ps confirms the Hostname output by whoami, and the name of the container (play-whoami-1) that we saw from the output of docker-compose up (scroll across to see the names).

CONTAINER ID   IMAGE               COMMAND     CREATED              STATUS              PORTS                NAMES
268742d8d212   containous/whoami   "/whoami"   About a minute ago   Up About a minute>80/tcp   play-whoami-1

Stopping docker-compose

Stopping docker-compose is similar to stopping a container started with docker. We can press Ctrl+c to exit.

We can confirm that the container has stopped by running docker ps -a

docker ps -a
CONTAINER ID   IMAGE               COMMAND     CREATED         STATUS                      PORTS     NAMES
268742d8d212   containous/whoami   "/whoami"   5 minutes ago   Exited (2) 16 seconds ago             play-whoami-1

Removing containers that were launched with docker-compose, is done easily with the command

docker-compose rm


In this step of the guide, we showed how docker-compose can be used to run, stop and remove applications. We saw how similar using docker-compose is to using docker commands, but also how running applications can be simpler this way, since the complexity is hidden in the docker-compose.yml file.

This makes up the last 20% of what I consider to be the requirements for a capable Docker user. There may be a few remaining concepts that this guide has not covered yet, but there is nothing major. The advantage of learning to use docker-compose, is that you can easily use other people's configuration files to launch nodes, websites and so on, without needing to know how everything was configured internally.

Last updated