9.1.1 Compose App Definition

A Compose app definition is the complete docker-compose.yml (or compose.yaml) file describing an entire multi-container application — its services, their configuration, the networks connecting them, and any volumes they need — serving as the single source of truth for how that application is structured and run.

The Overall Structure of a Definition

A Compose file is organized around top-level keys for services, networks, and volumes, each describing a distinct aspect of the application.

services:
  web:
    build: .
    ports:
      - "80:80"
  cache:
    image: redis:7

volumes:
  cache-data:

networks:
  app-net:

Why a Single File Captures the Whole Application

Rather than scattering an application's structure across separate, ad hoc commands or documentation, a Compose file consolidates everything needed to understand and run the complete application into one coherent, version-controllable artifact.

cat docker-compose.yml

Reading this single file provides a complete picture of the application's structure, without needing to consult separate documentation or reconstruct it from memory.

Versioning the Application Definition Alongside Its Code

Storing the Compose file within the same repository as the application's source code keeps the application's structural definition synchronized with the code it actually describes, evolving together over time.

git log -- docker-compose.yml

Reviewing this history reveals how the application's overall structure has evolved alongside the codebase itself.

Validating a Compose Definition

Before relying on a Compose file, validating its syntax and configuration catches mistakes before they cause a confusing runtime failure.

docker compose config

Why the Compose App Definition Matters

Treating the Compose file as the authoritative, version-controlled definition of an entire multi-container application provides a clear, reliable, and shareable description of how that application is structured, replacing fragmented knowledge or undocumented manual setup steps with a single, accurate source of truth.