Compose file versioning in Docker - Commands & Configuration

Introduction

Docker Compose files use versions to define how the file is read and which features are available. Using the right version helps Docker understand your app setup and run it correctly.

When you want to run multiple containers together with specific settings in one file.

When you need to use new Docker Compose features that require a certain file version.

When you want to ensure your Compose file works with the Docker Compose tool installed on your system.

When you want to share your app setup with others and make sure it runs the same way.

When you want to upgrade your Compose file to use newer syntax or capabilities.

Config File - docker-compose.yml

docker-compose.yml

version: '3.9'
services:
  web:
    image: nginx:1.23
    ports:
      - "8080:80"
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: example

version: Specifies the Compose file format version. Version 3.9 is the latest stable and supports modern features.

services: Defines the containers to run. Here, a web server and a database.

web: Runs an Nginx container exposing port 80 inside mapped to 8080 on the host.

db: Runs a Postgres container with a password set via environment variable.

Commands

Starts the containers defined in the docker-compose.yml file in detached mode so they run in the background.

Terminal

docker compose up -d

Expected Output

Creating network "default" with the default driver

Creating volume "default_pgdata" with default driver

Creating myapp_db_1 ... done

Creating myapp_web_1 ... done

→

-d - Run containers in the background (detached mode)

Lists the running containers started by Docker Compose to verify they are up and running.

Terminal

docker compose ps

Expected Output

NAME                COMMAND                  SERVICE             STATUS              PORTS

myapp_db_1          "docker-entrypoint.s…"   db                  running             

myapp_web_1         "nginx -g 'daemon of…"   web                 running             0.0.0.0:8080->80/tcp

Validates the docker-compose.yml file syntax and version compatibility without printing the full config.

Terminal

docker compose config --quiet

Expected Output

No output (command runs silently)

→

--quiet - Only show errors, no output if valid

Key Concept

If you remember nothing else from this pattern, remember: the Compose file version controls which features and syntax you can use and ensures Docker runs your app correctly.

Common Mistakes

Using an outdated version number like '2' when you want to use newer features.

Older versions do not support the latest Compose features and may cause errors or unexpected behavior.

Use the latest stable version like '3.9' to access all current features.

Omitting the version key entirely in the Compose file.

Docker Compose may default to an older version or fail to parse the file correctly.

Always specify the version explicitly at the top of the file.

Mixing syntax from different Compose versions in the same file.

This causes parsing errors because syntax rules differ between versions.

Stick to the syntax rules of the version declared in the file.

Summary

The Compose file version defines the syntax and features available in your docker-compose.yml file.

Use 'docker compose up -d' to start containers defined in the Compose file in the background.

Use 'docker compose ps' to check running containers and 'docker compose config --quiet' to validate the file.

Practice

1. What does the version field in a Docker Compose file specify?

easy

A. The version of the operating system hosting Docker

B. The version of the Docker Engine installed on the system

C. The version of the application running inside the container

D. The format and features Docker Compose should use to read the file

Solution

1. Step 1: Understand the role of the version field

   The version field tells Docker Compose which syntax and features to expect in the file.

2. Step 2: Differentiate from other version types

   This field is not about Docker Engine, app, or OS versions but about Compose file format.

3. Final Answer:

   The format and features Docker Compose should use to read the file -> Option D

4. Quick Check:

   Compose file version = file format and features [OK]

Hint: Version field controls Compose syntax, not Docker or app versions [OK]

Common Mistakes:

• Confusing Compose file version with Docker Engine version
• Thinking it sets app container version
• Assuming it relates to OS version

2. Which of the following is the correct way to specify the Compose file version in YAML?

easy

A. version: "3.9"

B. version : 3.9

C. version = "3.9"

D. "version" : 3.9

Solution

1. Step 1: Recall YAML syntax for key-value pairs

   YAML uses colon and space to assign values, and strings should be quoted if they contain dots.

2. Step 2: Identify correct quoting for version

   The version number with a decimal should be quoted as a string: "3.9".

3. Final Answer:

   version: "3.9" -> Option A

4. Quick Check:

   YAML version field quoted with colon = correct [OK]

Hint: Use colon and quotes for version like version: "3.9" [OK]

Common Mistakes:

• Using equals sign instead of colon
• Not quoting version with decimals
• Putting quotes around key instead of value

3. Given this Compose file snippet:

version: "2.4"
services:
  web:
    image: nginx
    ports:
      - "80:80"

What will happen if you run this with Docker Compose version 1.27.0?

medium

A. It will run successfully using version 2 features

B. It will fail because version 2.4 is not supported in 1.27.0

C. It will ignore the version and run with default settings

D. It will upgrade the Compose file version automatically

Solution

1. Step 1: Check Docker Compose 1.27.0 compatibility

   Docker Compose 1.27.0 supports Compose file version 2.4 syntax and features.

2. Step 2: Understand behavior on supported versions

   Since version 2.4 is supported, Compose will run the services as defined without errors.

3. Final Answer:

   It will run successfully using version 2 features -> Option A

4. Quick Check:

   Supported Compose version runs fine [OK]

Hint: Check Compose version supports file version before running [OK]

Common Mistakes:

• Assuming newer Compose versions are always required
• Thinking Compose auto-upgrades file versions
• Believing unsupported versions cause silent ignores

4. You have this Compose file:

version: "3.8
services:
  app:
    image: myapp
    ports:
      - "8080:80"

When running docker-compose up, you get an error. What is the likely cause?

medium

A. The ports mapping syntax is incorrect

B. The image name is invalid without a tag

C. The version number is not quoted, causing a YAML parsing error

D. Docker Compose does not support version 3.8

Solution

1. Step 1: Identify YAML syntax issue

   The version field with a decimal must be quoted as a string to avoid YAML parsing errors.

2. Step 2: Check other fields for errors

   Image name without tag is valid (defaults to latest), ports syntax is correct, and version 3.8 is supported.

3. Final Answer:

   The version number is not quoted, causing a YAML parsing error -> Option C

4. Quick Check:

   Unquoted decimal version causes YAML error [OK]

Hint: Always quote version numbers with decimals in Compose files [OK]

Common Mistakes:

• Not quoting version with decimals
• Assuming image needs explicit tag
• Misreading ports syntax as error

5. You want to use a new Compose feature available only in version 3.9, but your current Compose file uses version "3.7". What is the best way to update your Compose file to use the new feature safely?

hard

A. Add the new feature without changing the version field, it will work automatically

B. Change the version field to "3.9" and test the file with your Docker Compose version

C. Downgrade your Docker Compose to an older version that supports 3.7 features only

D. Remove the version field entirely to let Docker Compose decide

Solution

1. Step 1: Update the version field to match the new feature

   Set the version field to "3.9" to indicate use of new features introduced in that version.

2. Step 2: Test compatibility with your Docker Compose version

   Ensure your Docker Compose installation supports version 3.9 to avoid errors.

3. Final Answer:

   Change the version field to "3.9" and test the file with your Docker Compose version -> Option B

4. Quick Check:

   Update version field and verify Compose support [OK]

Hint: Match version field to features and test Compose version support [OK]

Common Mistakes:

• Using new features without updating version field
• Removing version field causing unpredictable behavior
• Ignoring Compose version compatibility