---
source: https://iinventedlight.com/library/notes/docker-compose-basics.md
title: "Docker Compose: the application model and compose.yaml"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed; prose restates or closely paraphrases cited source lines"
license_family: docker-docs-apache
rule_check: "needs rule check (family not in auto-publish rule; check.mjs auto-approves only usgov and arxiv-ccby)"
attribution: "Summary by iinventedlight (AI-assisted). Sources: Docker Docs, How Compose works, Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed; Docker Docs, Why use Compose?, Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-04
as_of: 2026-11-04
confidence: medium
untested: "No code was run for this note; only the fetched documentation pages were read."
category: coding-references
topic_area: "code-ai-eng: Docker"
tags: ['docker', 'compose', 'multi-container']
sources:
  - id: S1
    title: "How Compose works"
    publisher: Docker Docs
    url: https://docs.docker.com/compose/intro/compose-application-model/
    accessed: 2026-11-04
    license: "Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed"
  - id: S2
    title: "Why use Compose?"
    publisher: Docker Docs
    url: https://docs.docker.com/compose/intro/features-uses/
    accessed: 2026-11-04
    license: "Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed"
---
# Docker Compose: the application model and compose.yaml

**Answer:** Compose lets you define and manage multi-container apps in one YAML file. (S2) In the Compose Specification, a service is an abstract concept implemented on platforms by running the same container image, and configuration, one or more times. (S1)

## Building blocks

- In the Compose Specification, a network is a platform capability abstraction to establish an IP route between containers within services connected together. (S1)
- The Specification describes persistent data as a high-level filesystem mount with global options. (S1)
- From inside the container, configs behave like volumes: they're mounted as files. (S1)

## The Compose file

- The default path for a Compose file is compose.yaml (preferred) or compose.yml that is placed in the working directory. (S1)
- Compose also supports docker-compose.yaml and docker-compose.yml for backwards compatibility of earlier versions. (S1)
- If both files exist, Compose prefers the canonical compose.yaml. (S1)
- Compose offers a way for you to set a custom project name, so that the same compose.yaml file can be deployed twice on the same infrastructure by passing a distinct name. (S1)

## Day-to-day benefits

- Compose caches the configuration used to create a container. When you restart a service that has not changed, Compose reuses the existing containers. (S2)
- Compose supports variables in the Compose file, which you can use to customize your composition for different environments, or different users. (S2)

## Claims
- id: C1
  claim: A Compose service runs the same image and configuration one or more times.
  source: S1
  evidence: "and configuration, one or more times."
- id: C2
  claim: compose.yaml is the preferred default Compose file.
  source: S1
  evidence: "If both files exist, Compose prefers the canonical compose.yaml."
- id: C3
  claim: Compose reuses existing containers for unchanged services.
  source: S2
  evidence: "When you restart a service that has not changed, Compose reuses the existing containers."
- id: C4
  claim: Compose supports variables in the Compose file.
  source: S2
  evidence: "Compose supports variables in the Compose file."

## Sources
- [S1] How Compose works. Docker Docs. https://docs.docker.com/compose/intro/compose-application-model/ . License: Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed. Accessed 2026-11-04.
- [S2] Why use Compose?. Docker Docs. https://docs.docker.com/compose/intro/features-uses/ . License: Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed. Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).