How Compose works

How Compose works

Docker Compose relies on a YAML configuration file, usually named compose.yaml.

The compose.yaml file follows the rules provided by the Compose Specification in how to define multi-container applications.

👉 Compose Specification:

The Compose Specification is the latest and recommended version of the Compose file format. It helps you define a Compose file which is used to configure your Docker application’s services, networks, volumes, and more.

Legacy versions 2.x and 3.x of the Compose file format were merged into the Compose Specification. It is implemented in versions 1.27.0 and above (also known as Compose V2) of the Docker Compose CLI.

👉 The Compose file

The default path for a Compose file is compose.yaml (preferred) or compose.yml that is placed in the working directory. Compose also supports docker-compose.yaml and docker-compose.yml for backwards compatibility of earlier versions. If both files exist, Compose prefers the canonical compose.yaml.

Multiple Compose files can be merged together to define the application model. The combination of YAML files is implemented by appending or overriding YAML elements based on the Compose file order you set. Simple attributes and maps get overridden by the highest order Compose file, lists get merged by appending. Relative paths are resolved based on the first Compose file’s parent folder, whenever complimentary files being merged are hosted in other folders. As some Compose file elements can both be expressed as single strings or complex objects, merges apply to the expanded form

If you want to reuse other Compose files, or factor out parts of your application model into separate Compose files, you can also use include. This is useful if your Compose application is dependent on another application which is managed by a different team, or needs to be shared with others.


Consider an application split into a frontend web application and a backend service.

The frontend is configured at runtime with an HTTP configuration file managed by infrastructure, providing an external domain name, and an HTTPS server certificate injected by the platform’s secured secret store.

And The backend stores data in a persistent volume.

Both services communicate with each other on an isolated back-tier network, while the frontend is also connected to a front-tier network and exposes port 443 for external usage.

The example application is composed of the following parts:

  • 2 services, backed by Docker images: webapp and database

  • 1 secret (HTTPS certificate), injected into the frontend

  • 1 configuration (HTTP), injected into the frontend

  • 1 persistent volume, attached to the backend

  • 2 networks

    image: example/webapp
      - "443:8043"
      - front-tier
      - back-tier
      - httpd-config
      - server-certificate

    image: example/database
      - db-data:/etc/data
      - back-tier

    driver: flocker
      size: "10GiB"

    external: true

    external: true

  # The presence of these objects is sufficient to define them
  front-tier: {}
  back-tier: {}

let’s break down each part of the Docker Compose file you provided step by step:

Services Section:

frontend: This section defines a service named frontend. It uses the Docker image example/webapp to create containers. The service exposes port 443 of the container to port 8043 on the host machine. This means that incoming traffic on port 8043 of the host will be directed to port 443 inside the container running the frontend service.

  • ports: Maps the host machine's port 8043 to the container's port 443.

  • networks: Connects the frontend service to two Docker networks: front-tier and back-tier. This allows the frontend service to communicate with other services connected to these networks.

  • configs: Associates the frontend service with an external configuration named httpd-config. This configuration likely contains settings for an HTTP server like Apache.

  • secrets: Links the frontend service with an external secret named server-certificate. This secret probably contains SSL certificates or other sensitive information needed by the web server.

backend: This section defines a service named backend that uses the Docker image example/database to create containers. The backend service is simpler compared to frontend.

  • volumes: Mounts a Docker volume named db-data to the container's /etc/data directory. This volume is used to persist data for the database service.

  • networks: Connects the backend service to the back-tier Docker network. This network likely facilitates communication between backend services.

Volumes Section:

db-data: Defines a Docker volume named db-data using the Flocker driver. The volume's driver options specify a size of 10GiB. This volume is used by the backend service to store data persistently.

Configs Section:

httpd-config: Specifies an external configuration named httpd-config. This configuration is likely used by the frontend service, possibly containing settings for an Apache HTTP server.

Secrets Section:

server-certificate: Specifies an external secret named server-certificate. This secret is used by the frontend service, possibly containing SSL certificates or other sensitive information required by the web server.

Networks Section:

front-tier and back-tier: Defines two Docker networks named front-tier and back-tier. Although the definition in the file is empty, referencing these networks within services automatically creates and connects containers to them. These networks enable communication between services and provide isolation and segmentation within the Docker environment.

This Docker Compose file sets up a frontend web application (frontend service) with a specific image, ports, networks, configurations, and secrets. It also includes a backend database (backend service) with its own image, volume, and network configurations. The file ensures that the necessary volumes, configurations, secrets, and networks are available for the services to function properly within the Docker environment.

Did you find this article valuable?

Support Megha Sharma by becoming a sponsor. Any amount is appreciated!