How to use docker compose alpha dry-run command to test changes

Introduction

In this lab, you will learn how to use the docker compose alpha dry-run command to test changes to your Docker Compose configuration without actually executing them. This is a valuable tool for verifying your docker-compose.yaml file and understanding the potential impact of commands before applying them.

You will begin by preparing a simple docker-compose.yaml file. Then, you will use the dry-run flag with basic Docker Compose commands to observe the simulated output and understand how the command would behave. Finally, you will apply dry-run to a command that would typically make changes, allowing you to see the intended actions without altering your system.

Skills Graph

Prepare a simple docker-compose.yaml file

In this step, we will prepare a simple docker-compose.yaml file. This file will define a basic service that we can use to demonstrate the dry-run functionality of Docker Compose.

First, we need to install Docker Compose. Since it's not pre-installed in this environment, we will download the binary and make it executable.

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

This command downloads the Docker Compose binary for your system's architecture and saves it to /usr/local/bin/docker-compose. The chmod +x command makes the file executable.

Now, let's verify that Docker Compose is installed correctly by checking its version.

docker-compose version

You should see output indicating the installed version of Docker Compose.

Next, we will create a directory for our project and navigate into it.

mkdir ~/project/my-compose-app
cd ~/project/my-compose-app

We are now in the ~/project/my-compose-app directory, where we will create our docker-compose.yaml file.

Now, let's create the docker-compose.yaml file using the nano editor.

nano docker-compose.yaml

Inside the nano editor, paste the following content:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"

This docker-compose.yaml file defines a single service named web. This service uses the nginx:latest Docker image and maps port 80 on the host to port 80 in the container.

Save the file by pressing Ctrl + O, then press Enter, and exit the editor by pressing Ctrl + X.

We have now successfully created a simple docker-compose.yaml file.

Use dry-run with a basic compose command

In this step, we will use the dry-run flag with a basic Docker Compose command to see how it works. The dry-run flag allows you to see what actions Docker Compose would take without actually performing them. This is useful for understanding the potential impact of a command before executing it.

We will use the docker-compose config command with the dry-run flag. The config command validates and displays the Compose file configuration. Adding dry-run to this command doesn't change its behavior significantly since config is already a non-destructive command, but it's a good starting point to understand the flag's syntax.

First, make sure you are in the directory containing your docker-compose.yaml file.

cd ~/project/my-compose-app

Now, execute the docker-compose config --dry-run command.

docker-compose config --dry-run

You should see the parsed configuration of your docker-compose.yaml file printed to the console. This output is the same as running docker-compose config without the dry-run flag in this case, because config is inherently a dry-run operation.

The output confirms that Docker Compose successfully parsed your docker-compose.yaml file and understands the services and configurations defined within it.

Observe the output of the dry-run command

In this step, we will carefully observe the output of the docker-compose config --dry-run command we executed in the previous step. Understanding this output is crucial for seeing how Docker Compose interprets your docker-compose.yaml file.

The output you saw is the validated configuration in YAML format. It represents how Docker Compose understands the services, networks, and volumes defined in your file.

Let's look at the key parts of the output based on our simple docker-compose.yaml:

services:
  web:
    build:
      context: /home/labex/project/my-compose-app
    container_name: my-compose-app-web-1
    image: nginx:latest
    ports:
      - published: 80
        target: 80
    restart: "no"

You will see the services section, and within it, the web service.

• image: nginx:latest: This confirms that Docker Compose correctly identified the image to be used for the web service.
• ports:: This section shows the port mapping. published: 80 indicates the host port, and target: 80 indicates the container port. This matches what we defined in our docker-compose.yaml.
• container_name: my-compose-app-web-1: Docker Compose automatically generates a default container name based on the project directory name and the service name.
• build:: Even though we specified an image, Docker Compose includes a build section with the context set to the current directory. This is part of the internal representation and doesn't mean it will build an image if you only specified an image.
• restart: 'no': Docker Compose defaults the restart policy to no if not specified.

This output is a representation of the final configuration that Docker Compose would use if you were to run a command like docker-compose up. The dry-run flag, when used with commands that would make changes (which we will see in the next step), would show you the actions it would take, not just the configuration.

For the config command, the dry-run flag primarily serves to validate the syntax and structure of your docker-compose.yaml file. If there were any syntax errors, the config command (with or without dry-run) would report them.

Use dry-run with a command that would make changes

In this step, we will use the dry-run flag with a Docker Compose command that would typically make changes to your system, such as docker-compose up. This will demonstrate how dry-run can show you the intended actions without actually creating containers or networks.

The docker-compose up command, without dry-run, would pull the specified images (if not already present), create networks, and start containers based on your docker-compose.yaml file. By adding the dry-run flag, we can see the steps it would take without performing them.

First, ensure you are in the correct directory:

cd ~/project/my-compose-app

Now, execute the docker-compose up --dry-run command.

docker-compose up --dry-run

You will see output indicating the actions Docker Compose would perform. For our simple docker-compose.yaml, the output might look something like this:

Would create network "my-compose-app_default"
Would create service "web"
  Would pull image "nginx:latest"
  Would create container "my-compose-app-web-1"

This output clearly shows that Docker Compose intends to:

1. Create a default network named my-compose-app_default.
2. Create a service named web.
3. Pull the nginx:latest image (if it's not already available locally).
4. Create a container named my-compose-app-web-1 for the web service.

Notice that none of these actions are actually performed. No network is created, no image is pulled, and no container is started. The dry-run flag prevents any actual changes to your Docker environment.

This is incredibly useful for:

• Previewing changes: Before deploying a complex application, you can use dry-run to see exactly what Docker Compose will do.
• Troubleshooting: If a docker-compose up command is failing, dry-run can help you understand the initial steps and identify potential issues in your configuration.
• Learning: It allows you to experiment with different docker-compose.yaml configurations and see their impact without affecting your system.

You can use the dry-run flag with other Docker Compose commands as well, such as down, start, stop, and rm, to see what resources would be affected.

Summary

In this lab, we learned how to prepare a simple docker-compose.yaml file by first installing Docker Compose and then creating a directory and the YAML file with a basic Nginx service definition. We then explored the use of the dry-run flag with Docker Compose commands.

We observed how the dry-run flag allows us to preview the actions that a command would perform without actually making any changes to the system. This is a valuable tool for testing changes to our docker-compose.yaml file and understanding the potential impact of commands before execution.