How to Use Booleans in docker-compose.yml

1. Overview

Boolean data types represent the values true or false. In docker-compose.yml, using booleans can be confusing because of how YAML processes data and how Docker Compose handles environment variables. That’s why we need to understand how YAML and Docker Compose work with booleans. As a result, we can ensure that docker-compose.yml works correctly.

In this tutorial, we’ll discuss how to handle booleans in docker-compose.yml.

2. Understanding the Problem

To demonstrate, let’s use the environment section in docker-compose.yml. In docker-compose.yml, it’s common to set environment variables that are useful for passing configuration values to containers. However, while working with boolean values in the environment section, we may encounter errors.

2.1. How YAML Interprets Boolean Values

YAML, the language we use to write docker-compose.yml files, supports YAML-specific interpretations of booleans. It’s case-insensitive in that true, false, True, and False are interpreted as booleans. Additionally, there are other values it may interpret as booleans as well:

• yes – Boolean true
• no – Boolean false
• on – Boolean true
• off – Boolean false

So, above are common values that YAML treats as booleans. Notably, the version of YAML influences how boolean values are interpreted. For instance, YAML 1.2 used in modern Docker Compose discards yes and no as booleans unlike YAML 1.1. To clarify, YAML 1.1 doesn’t treat values like yes and no as booleans unless we specify them explicitly.

2.2. How Docker Compose Handles Boolean Values

Although YAML supports boolean values, Docker Compose doesn’t accept boolean values for environment variables. To explain, Docker Compose doesn’t support booleans as a valid data type since it only supports string, number, or null values. Therefore, it’s not uncommon for Docker Compose to throw an error when we use a boolean value for an environment variable in the docker-compose.yml file.

Now, let’s examine a common error that may arise when we use unquoted boolean values such as true and yes as environment variables in docker-compose.yml. Quoting these values conveniently ensures compatibility across different YAML versions.

2.3. Showing the Error

To show the error, let’s start by creating a docker-compose.yml file containing the content:

version: '3.8'
services:
  app:
    image: nginx:latest
    environment:
      AUTO_APPLY: true

Now, let’s see what happens when we run docker-compose up -d:

$ docker-compose up -d
ERROR: The Compose file './docker-compose.yml' is invalid because:
services.app.environment.AUTO_APPLY contains true, which is an invalid type, it should be a string, number, or a null

The error happens because of using true as a value for the environment variable AUTO_APPLY. Docker Compose always expects environment variables as strings since containers receive environment variables as text.

Here, we simply wrap the boolean value in quotes. This converts the value to a string which Docker Compose accepts:

version: '3.8'
services:
  app:
    image: nginx:latest
    environment:
      AUTO_APPLY: 'true'

Above, Docker Compose treats ‘true’ as a string and processes it without any errors.

$ docker-compose up -d
Creating docker-management_app_1 ... done

This modification satisfies the requirement that Docker Compose environment variables can be strings.

3. Practical Examples

In this section, let’s illustrate with a practical example. Let’s create an application that expects a boolean value rather than a string.

3.1. Application Excepts Booleans Instead of Strings

To illustrate, let’s consider the Python application app.py which expects the AUTO_APPLY environment variable to be a boolean:

import os

# Fetches the value of AUTO_APPLY and defaults to "false" if not set
auto_apply = os.getenv("AUTO_APPLY", "false").lower() == "true"
print(f"Auto Apply: {auto_apply}")

It reads AUTO_APPLY to determine whether it should enable a feature or not. Additionally, it converts the string “false” to a boolean:

• auto_apply = os.getenv(“AUTO_APPLY”, “false”) – fetches the value of AUTO_APPLY and if it’s not set, it defaults to the string “false”
• .lower() – ensures case-insensitivity by converting the value to lowercase, for example, “True” to “true”
• == “true” – sets auto_apply to True if value is “true” otherwise auto_apply becomes False

Next, let’s define docker-compose.yml file:

version: '3.8'
services:
  app:
    image: python:3.10-slim
    working_dir: /app
    volumes:
      - ./app.py:/app/app.py
    environment:
      AUTO_APPLY: "false"
    command: python3 app.py

Above, we set the value of the AUTO_APPLY environment variable to “false”:

$ docker-compose up
Creating network "app_default" with the default driver
Creating app_app_1 ... done
Attaching to app_app_1
app_1  | Auto Apply: False
app_app_1 exited with code 0

Here, we convert the value of the environment variable AUTO_APPLY within the Python application logic. This ensures the application behaves as expected and still adheres to the requirement that Docker Compose environment variables can either be a string, a number, or null.

3.2. Interpretation of yes and no

Here, let’s change the value of AUTO_APPLY to yes:

version: '3.8'
services:
  app:
    image: python:3.10-slim
    working_dir: /app
    volumes:
      - ./app.py:/app/app.py
    environment:
      AUTO_APPLY: yes
    command: python3 app.py

Now, this leads to unexpected behavior since YAML treats yes and no as boolean values true and false respectively:

$ docker-compose up
ERROR: The Compose file './docker-compose.yml' is invalid because:
services.app.environment.AUTO_APPLY contains true, which is an invalid type, it should be a string, number, or a null

From the example above, we see that YAML interprets yes as true whereas using no without quotes results to false causing a similar issue. Therefore, we need to quote yes so that Docker Compose treats it as a string:

environment:
    AUTO_APPLY: "yes"

Next, let’s modify app.py:

auto_apply = os.getenv("AUTO_APPLY", "false").lower() in ["true", "yes", "on"]

In app.py, we replace == “true” with in [“true”, “yes”, “on”]. This modification simply checks if the lowercase value is one of the strings “true”, “yes” or “on”. The expression evaluates to True if the value matches any of these strings. Otherwise, it evaluates to False.

4. Conclusion

In this article, we looked at how to handle booleans in docker-compose.yml by putting into account how YAML and Docker Compose interpret boolean values.

In this case, we saw that YAML interprets unquoted values such as yes, no, on and off as booleans. However, Docker Compose expects only strings, numbers, or null as the value for environment variables. As a result, this inconsistency can lead to errors such as “contains true, which is an invalid type”.

That’s why we need to quote the environment variable values to ensure Docker Compose treats them as strings. Additionally, we handled boolean conversions in the Python application logic maintaining compatibility with Docker Compose. For example, converting the strings “true” and “yes” in the application ensures consistency. So, quoting values and handling boolean conversions programmatically helps us to manage booleans and avoid unexpected behavior in containerized applications.