Docker Compose Foundations: Services, Images, Builds, Networks, Volumes, Environment, and Project Lifecycle: Concepts, Architecture, and Mental Model

1. The problem: a multi-container application has more state than a list of docker run commands

By Chapter 14 you can build, identify, distribute, and retrieve images. Real applications often need several related containers plus networks, persistent storage, environment-specific configuration, health observations, and repeatable lifecycle commands. Hand-writing independent docker run commands makes those relationships easy to drift.

Compose solves the declaration problem. A Compose file describes desired application components; the Compose CLI resolves interpolation and file rules into a normalized model, chooses a project identity, and asks the active Docker Engine to create or reconcile concrete resources. The project name is not cosmetic: it groups and isolates resources and appears in canonical Compose labels.

2. Mental model: file + interpolation → normalized model → project → Engine resources → observed state

flowchart TD
  A[compose.yaml + optional override files] --> B[Interpolation inputs shell / --env-file / .env]
  B --> C[docker compose config normalized model]
  C --> D[Project identity -p / COMPOSE_PROJECT_NAME / name]
  D --> E[Services]
  D --> F[Project networks]
  D --> G[Project volumes]
  E --> H[Image pull or build]
  H --> I[Service containers]
  F --> I
  G --> I
  I --> J[Runtime evidence ps logs inspect health ports]
            

The Compose file is declarative input, not runtime evidence. docker compose config proves what Compose resolved. Engine inspection proves what exists. Application probes and health evidence prove what the workload can actually do.

3. Define the objects before operating them

4. Project naming is an isolation control

Current Compose project-name precedence is: -p on the CLI, then COMPOSE_PROJECT_NAME, then top-level name:, then the project-directory basename, then the current-directory basename when no file is specified. The same Compose model can therefore create two isolated application instances by using two project names.

Compose uses the project identity to scope default resource names and sets canonical labels such as com.docker.compose.project. Network and volume resources also receive Compose resource labels. These labels are often safer diagnostic selectors than guessing generated names.

docker compose version
docker compose config --services
docker compose config --networks
docker compose config --volumes

# After a project exists, inspect by canonical label rather than by name guessing:
docker ps -a --filter label=com.docker.compose.project=da-compose15
docker network ls --filter label=com.docker.compose.project=da-compose15
docker volume ls --filter label=com.docker.compose.project=da-compose15

5. Interpolation environment is not the same as the container environment

Compose can substitute variables into YAML values before creating resources. Current Docker Compose gives shell variables higher interpolation precedence than values from --env-file, which in turn override the default project .env path. You can inspect interpolation inputs with docker compose config --environment.

Container environment precedence is a separate problem. CLI run -e overrides relevant Compose-file values; Compose environment generally outranks env_file; image ENV is lower when Compose provides a value. A file named .env is therefore configuration input, not a secret manager. Chapter 15 deliberately uses only synthetic non-secret values.

6. Default networking: service-name discovery, not fixed container IPs

For ordinary local development, Compose creates one project default bridge network. Containers attached to that network are discoverable by service name through Docker's internal DNS. Recreated containers can receive new IP addresses, so application configuration should prefer stable service names rather than persisted IPs.

A host-published port is a separate path. Service-to-service traffic normally targets the container port through the Compose network; host users reach the published host address/port. Publishing 127.0.0.1:8080:80 intentionally bounds the lab listener to loopback.

7. Named volumes outlive ordinary container replacement

A named volume is an Engine storage object attached to a service container. docker compose down removes project containers and ordinary project networks by default, but it does not remove named volumes unless volume deletion is explicitly requested. This is a crucial lifecycle boundary: replacing a container is not the same as deleting its persistent data.

Bind mounts instead couple the service to a host path. They can be appropriate for editable source code or explicit host integration, but they reduce portability because the host path and permissions become part of runtime correctness.

8. Read-only preflight: prove client, context, Compose, and model state first

docker version
docker info
docker context show
docker compose version

# In a Compose project directory, before creating anything:
docker compose config --quiet
docker compose config --environment
docker compose config --services
docker compose config --networks
docker compose config --volumes

# If a project already exists:
docker compose ps -a
docker compose images

docker compose config is particularly valuable because it merges files, interpolates variables, expands short syntax, and renders the model that Compose intends to apply. It does not prove the Engine accepted or is currently running that model; follow it with runtime evidence.

9. Compose is not a magical production orchestrator

Compose gives a portable application model and excellent local/single-Engine lifecycle ergonomics. It does not, by itself, add a scheduler across hosts, distributed consensus, automatic multi-node rescheduling, or a complete secrets/identity/observability platform. Some Compose specification attributes can map to richer platforms, but the local Docker Engine execution path remains a concrete single-platform implementation.

This course therefore treats Compose as a declarative application model whose outputs must still be verified at the image, container, network, storage, security, and application layers.

10. Common misconceptions to reject early

• “Service name equals container hostname everywhere.” Service-name discovery is network-scoped; custom network modes, aliases, multiple replicas, and hostname settings change details.
• “.env is a secret vault.” It is configuration/interpolation input and can be accidentally committed or exposed.
• “up means ready.” It proves Compose created/started resources, not that an application dependency is healthy.
• “down deletes all data.” Named volumes are preserved by default; explicit volume deletion is a different action.
• “Directory name is harmless.” It can become the project name and therefore affect which resources a command targets.

Knowledge check

Official references and version notes

• Docker Docs — Compose application model: projects, services, networks, volumes, and lifecycle.
• Docker Docs — Compose Specification reference: current declarative model and attributes.
• Docker Docs — docker compose config: canonical rendering, interpolation environment, service/network/volume views, hashes and digest resolution.
• Docker Docs — project naming: precedence and isolation.
• Docker Docs — interpolation and container environment precedence.
• Docker Docs — Compose networking: default network and service-name discovery.
• Docker Docs — docker compose down: default teardown and explicit volume deletion semantics.
• Docker Compose v5.5.1 release (2026-09-03). Labs record the actually installed version and do not assume every host matches upstream.