How to use docker stack config command to inspect merged Compose files

Introduction

In this lab, you will learn how to use the docker stack config command to inspect the final, merged configuration of your Docker Compose files. This is a crucial skill for understanding how Docker interprets your Compose definitions, especially when dealing with multiple files or environment variables. You will begin by outputting the configuration from a single Compose file, including the necessary steps to install Docker Compose in the LabEx environment.

Following that, you will explore how to merge and output the configuration from multiple Compose files, demonstrating how Docker combines definitions from different sources. You will also learn how to output configuration directly from standard input and how to skip interpolation of environment variables when generating the configuration output. These steps will provide you with a comprehensive understanding of the docker stack config command's capabilities for debugging and verifying your Docker Compose setups.

Output the final config from a single Compose file

In this step, you will learn how to output the final configuration from a single Docker Compose file. This is useful for debugging or understanding the final state of your Compose file after all variables and extensions have been processed.

First, let's install Docker Compose. Since it's not pre-installed in the LabEx VM environment, we need to download and install it. We will download the latest stable version.

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

This command downloads the Docker Compose binary from the official GitHub repository. $(uname -s) and $(uname -m) are used to get the operating system and architecture of the VM, ensuring you download the correct binary.

Next, we need to give the downloaded binary executable permissions.

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

This command makes the docker-compose command executable.

Now, let's verify the installation by checking the version.

docker-compose --version

You should see the installed version of Docker Compose printed to the console.

Before we can output the configuration, we need a Docker Compose file. Let's create a simple one in the ~/project directory.

nano ~/project/docker-compose.yaml

Paste the following content into the docker-compose.yaml file:

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

This is a simple Compose file that defines a single service named web using the nginx:latest image and mapping port 80 on the host to port 80 in the container.

Save the file by pressing Ctrl + X, then Y, and Enter.

Now, navigate to the ~/project directory where you saved the docker-compose.yaml file.

cd ~/project

To output the final configuration from this Compose file, we use the docker-compose config command.

docker-compose config

This command reads the docker-compose.yaml file in the current directory and outputs the final merged configuration to the standard output. You should see the YAML content of your docker-compose.yaml file printed, potentially with some additional default values added by Docker Compose.

Merge and output config from multiple Compose files

In this step, you will learn how to merge configurations from multiple Docker Compose files and output the final combined configuration. This is a powerful feature that allows you to define a base configuration and then override or extend it with additional files, which is useful for managing different environments (e.g., development, staging, production).

We will continue working in the ~/project directory. In the previous step, we created a docker-compose.yaml file. Now, let's create another Compose file to extend the base configuration. We'll name it docker-compose.override.yaml.

nano ~/project/docker-compose.override.yaml

Paste the following content into the docker-compose.override.yaml file:

version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html

This override file modifies the web service defined in docker-compose.yaml. It changes the host port mapping from 80 to 8080 and adds a volume mount to serve static HTML content from a local directory named html.

Save the file by pressing Ctrl + X, then Y, and Enter.

Now, let's create the html directory and a simple index.html file within it.

mkdir ~/project/html
nano ~/project/html/index.html

Paste the following content into ~/project/html/index.html:

<h1>Hello from Nginx!</h1>

Save the file by pressing Ctrl + X, then Y, and Enter.

By default, Docker Compose automatically looks for docker-compose.yaml and docker-compose.override.yaml in the current directory and merges them. The configurations in the override file take precedence.

To see the merged configuration, make sure you are in the ~/project directory and run the docker-compose config command again.

cd ~/project
docker-compose config

You should now see the combined configuration, where the web service has the port mapping 8080:80 and the volume mount ./html:/usr/share/nginx/html.

You can also explicitly specify which Compose files to use with the -f flag. The order in which you specify the files matters, as later files override earlier ones.

For example, to explicitly merge docker-compose.yaml and docker-compose.override.yaml, you can run:

docker-compose -f docker-compose.yaml -f docker-compose.override.yaml config

This will produce the same merged output as running docker-compose config without the -f flag in this case, because docker-compose.override.yaml is automatically detected and merged after docker-compose.yaml.

Output config from stdin

In this step, you will learn how to output the final configuration from a Docker Compose file provided via standard input (stdin). This is useful when you want to generate a Compose file dynamically or pipe the output of another command directly to docker-compose config.

We will continue working in the ~/project directory. Instead of reading from a file, we will pipe the content of a Compose configuration directly to the docker-compose config command.

Let's use the cat command to output the content of our docker-compose.yaml file and pipe it to docker-compose config.

cd ~/project
cat docker-compose.yaml | docker-compose config -f -

In this command:

cat docker-compose.yaml outputs the content of the docker-compose.yaml file to standard output.
| is the pipe operator, which redirects the standard output of the cat command to the standard input of the docker-compose config command.
docker-compose config -f - tells docker-compose config to read the configuration from standard input (-) instead of a file.

You should see the same output as when you ran docker-compose config in the first step, which is the configuration from docker-compose.yaml.

You can also pipe a different configuration directly. For example, let's pipe a simple configuration for a redis service.

echo "version: '3.8'\nservices:\n  redis:\n    image: redis:latest" | docker-compose config -f -

In this command:

echo "version: '3.8'\nservices:\n redis:\n image: redis:latest" outputs the YAML string for a simple Compose file with a redis service. The \n creates newlines in the output.
| pipes this string to the docker-compose config command.
docker-compose config -f - reads the configuration from standard input.

The output should be the YAML configuration for the redis service.

This method is particularly useful when you are generating Compose configurations programmatically or when you want to quickly test a configuration without saving it to a file.

Output merged config skipping interpolation

In this step, you will learn how to output the merged configuration from multiple Docker Compose files while skipping variable interpolation. By default, docker-compose config interpolates environment variables. Skipping interpolation can be useful when you want to see the raw configuration with variables still present, for example, when debugging or generating a template.

We will continue working in the ~/project directory with our docker-compose.yaml and docker-compose.override.yaml files.

First, let's add an environment variable to our docker-compose.yaml file to demonstrate interpolation.

nano ~/project/docker-compose.yaml

Modify the docker-compose.yaml file to include an environment variable in the image name:

version: "3.8"
services:
  web:
    image: nginx:${NGINX_VERSION:-latest}
    ports:
      - "80:80"

Here, ${NGINX_VERSION:-latest} is a variable that will be replaced by the value of the NGINX_VERSION environment variable. If NGINX_VERSION is not set, it will default to latest.

Save the file by pressing Ctrl + X, then Y, and Enter.

Now, let's set the NGINX_VERSION environment variable and then run docker-compose config to see the interpolation in action.

cd ~/project
export NGINX_VERSION=1.21
docker-compose config

You should see the merged configuration, and the image name for the web service should now be nginx:1.21.

To output the merged configuration without interpolating the variables, we use the --no-interpolate flag with the docker-compose config command.

docker-compose --no-interpolate config

This time, the output should show the image name as nginx:${NGINX_VERSION:-latest}, with the variable placeholder still present, even though the NGINX_VERSION environment variable is set.

This flag is helpful when you want to see the exact configuration as written in your Compose files, before any variable substitution takes place.

Summary

In this lab, you learned how to use the docker-compose config command to inspect the final configuration of Docker Compose files. You began by installing Docker Compose in the LabEx VM environment, ensuring you downloaded the correct binary for the system architecture and granting it executable permissions. You then verified the installation by checking the version.

Following the installation, you created a simple docker-compose.yaml file defining a basic web service. You then used the docker-compose config command to output the final configuration from this single Compose file, demonstrating how to view the processed state of your Compose definition.