Use Docker Compose to simplify your Docker environment configuration

Mon, 30 Jan 2023 00:00:00 GMT

Why use Docker Compose

Docker Compose is a container orchestration tool you can use to configure the entirety of your application's Docker environment inside a single declarative config file, including multiple containers, networking, and volume mounts for persistent data. It is a self-documenting alternative to running individual 'Docker Run' commands.

Using Docker Compose, you create a single YAML formatted configuration file named 'docker-compose.yml' by default. Inside that file lives what are essentially a collection of parameters that function much like Docker Run commands, complete with the containers you want to create, images they should be created from, environment variables that should be set, and more. You can then execute a single command against this file which creates your containers and your desired environment for them all at once. Likewise, you can pull updated images for all of your containers or tear down the entire stack all at once as needed. You can even version control your docker compose file using a tool like Git. With Docker Compose, your documentation is your configuration, and it's all in one place.

Installing Docker Compose

Installing the docker compose plugin in easy. Once you've installed the Docker Engine and Docker CLI, you'll generally just use your Linux distro's package manager to install the docker compose plugin. For Ubuntu or other Debian-based distro, just run

sudo apt-get update
sudo apt-get install docker-compose-plugin

For other distributions, see the documentation on installing docker compose here:

Install the Compose plugin

How to install Docker Compose on Linux

The Docker Compose File

The Docker Compose file itself is very straightforward. It's in YAML format, so indentation should be consistent, using either two spaces or four. Let's take a look at an example compose file for a single MSSQL Server container.

version: '3.8' 
services:
    mssqlserver:
        image: mcr.microsoft.com/mssql/server:2019-latest
        environment:
            - ACCEPT_EULA=Y
            - MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>
        ports:
            - '1433:1433'
        volumes:
            - '<host_directory>/data:/var/opt/mssql/data'
            - '<host_directory>/log:/var/opt/mssql/log'
            - '<host_directory>/secrets:/var/opt/mssql/secrets'

A docker-compose.yml file with configuration for a single container

The newest version of Docker Compose adapted the Compose Specification for Docker Compose files. In this newest specification, the Version: property is not requred.

Every compose file should begin with the same two lines*. The rest are dependent on your desired configuration.

The first is the version: property. This defines the compose file version. At the time of writing this is '3.8'*.

The second is the services: property. This is the top level of your compose file, under which you'll configure each required container/service.

The third property is the name of your first service, in this case mssqlserver:. This is an arbitrary friendly name you choose to identify your service.

The fourth property and so on map directly to docker run commands you may be familiar with. This also makes it easy to translate between docker run commands and their docker compose file counterparts. At the end of a docker run command you will have the image and version tag you want to pull and use for your container. In compose, we use the image: property, then the value will be the same as it would be in a docker run command, in this case mcr.microsoft.com/mssql/server:2019-latest. This will pull the MSSQL server image from Microsoft, and due to the 2019-latest tag, it will pull the newest version of 2019 specifically.

The fifth property is environment: In a docker run command, you would specify each environment variable in with an -e option, followed by the environment variable in KEY:VALUE format, for each environment variable you wish to set. In compose, we simply define the environment: property once, then list each environment variable in KEY:VALUE format in list form underneath. So -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>' becomes:

environment:
    - ACCEPT_EULA=Y
    - MSSQL_SA_PASSWORD=<YourStrong!Passw0rd>

The sixth property is ports: In a docker run command, you'd specify any host port to container port mappings with the -p option, followed by a single mapping in hostport:containerport format, for each port you'd like to expose. In compose, we define the ports: property once, then list each port mapping in hostport:containerport format in a list underneath that property. So -p 1433:1433 becomes

ports:
    - '1433:1433'

The final property in our example docker compose file is volumes: and this is where you'll define host directories that you want to map to container directories in order to persist your data. In a docker run command, you'd specify your bind mounts with the -v switch, followed by a single mapping in hostdirectory:containerdirectory format, for each bind mound you'd like to create. In compose, we define the volumes: property once, then list each bind mount in hostdirectory:containerdirectory format in a list underneath that property. So

-v <host_directory>/data:/var/opt/mssql/data

-v <host_directory>/log:/var/opt/mssql/log

-v <host_directory>/secrets:/var/opt/mssql/secrets

Becomes:

volumes:
    - '<host_directory>/data:/var/opt/mssql/data'
    - '<host_directory>/log:/var/opt/mssql/log'
    - '<host_directory>/secrets:/var/opt/mssql/secrets'

There are many more properties you can set in your docker-compose.yml file, but these are all we need to get started with this container. If you'd like to look into other example files and see all the possible configurations you can make, check out the official compose file v3 reference sheet here:

[

Compose file version 3 reference

Compose file reference

The docker compose command

Now that we've created our docker-compose.yml file, we can run a single command against that file that will pull all the necessary images, create any appropriate docker networks, create and start each container we've configured along with all our port mappings and bind mounts.

First, we'll need to open a terminal and change directory into the one which contains our docker-compose.yml file. Then we can run any docker compose commands we want, and docker compose will look in the current directory for our docker-compose.yml file and execute the command against it.

`docker compose up -d`

This command will create and/or start our entire environment as defined in our compose file. The -d option will run the containers in "detached mode", which will essentially run our containers in the background. Generally speaking this is the command you'll use to start your entire docker stack.

`docker compose up`

This command will do the same thing as docker compose up -d except it will run your containers in the foreground, with the full output of each container's logs displayed interactively in your shell. This is useful if you'd like to troubleshoot issues with your containers and get a centralized look at all their logs in one place.

`docker compose down`

This command tears down your entire docker environment, stopping your containers as well as removing them, their images, and any volumes or networks you've created for them.

`docker compose pull`

This command pulls any images associated with the services you've defined in your docker-compose.yml file but doesn't start the containers.

In addition to docker compose commands, you can also run all the same docker commands against your docker environment.

Updating your containers

Docker compose makes updating your containers a breeze. simply run docker compose pull against your compose file and docker will pull the latest version you've tagged for each service in your compose file, but won't disrupt any running containers. Then you can run docker compose up -d while your containers are running and it will recreate the containers which have new images that have been pulled. Any containers that are already on the most up-to-date image will not restart. This process can easily be added as a scheduled task using a tool like cron for automated container updates.

Summary

Docker Compose makes it easy to configure your docker environment and store those configurations in a single file that can be backed up and version-controlled, and run in a consistent manner every single time. The more services you add, the more convenient the compose file becomes.

Infernal Error