docker-impl-compose-workflows

Quick Reference

Compose File Search Order

Compose searches for files in this order:

compose.yaml (preferred)
compose.yml
docker-compose.yaml
docker-compose.yml

ALWAYS use compose.yaml for new projects. The docker-compose.* names exist only for backward compatibility.

NEVER include a version: field. It is deprecated and ignored by modern Compose.

Environment Variable Precedence (Highest to Lowest)

Priority	Source	Example
1 (highest)	`docker compose run -e` CLI flag	`docker compose run -e DEBUG=1 web`
2	Shell/interpolation in `environment` or `env_file`	`${DEBUG}` resolved from host shell
3	`environment` attribute in compose.yaml	`environment: DEBUG: "true"`
4	`env_file` attribute files	`env_file: .env.local`
5 (lowest)	Image `ENV` directive	`ENV DEBUG=false` in Dockerfile

Variable Interpolation Syntax

Syntax	Behavior
`$VAR` or `${VAR}`	Direct substitution
`${VAR:-default}`	Use `default` if VAR is unset or empty
`${VAR-default}`	Use `default` only if VAR is unset
`${VAR:?error}`	Error if VAR is unset or empty
`${VAR?error}`	Error if VAR is unset
`${VAR:+replacement}`	Use `replacement` if VAR is set and non-empty
`${VAR+replacement}`	Use `replacement` if VAR is set

Use $$ to produce a literal $ sign. Interpolation applies to unquoted and double-quoted values only. Single-quoted values in .env files are literal.

Merge Rules (Multiple Compose Files)

Field Type	Behavior	Examples
Scalar (single-value)	Later file replaces earlier	`image`, `command`, `mem_limit`
Sequence (multi-value)	Values concatenated	`ports`, `expose`, `dns`, `tmpfs`
Mapping (key-value)	Merge by key; later overrides matching keys	`environment`, `labels`, `volumes`

Critical Warnings

NEVER use environment variables for secrets (passwords, tokens, API keys). ALWAYS use Docker secrets or mounted secret files instead.

NEVER assume depends_on waits for service readiness. ALWAYS combine with condition: service_healthy and a healthcheck.

ALWAYS use docker compose config to verify the resolved configuration after merging multiple files or applying overrides.

NEVER use container_name on services you intend to scale. It prevents scaling because names must be unique.

Profiles

Assignment and Activation

Services WITHOUT a profiles attribute are ALWAYS started. Services WITH profiles start only when their profile is activated.

services:
  app:                              # No profile = ALWAYS enabled
    image: myapp
  phpmyadmin:
    image: phpmyadmin
    profiles: [debug]               # Only with debug profile
  frontend:
    image: node
    profiles: [frontend, dev]       # Multiple profiles

Activation Methods

# CLI flag (repeatable)
docker compose --profile debug up
docker compose --profile frontend --profile debug up
docker compose --profile "*" up          # Enable ALL profiles

# Environment variable (comma-separated)
COMPOSE_PROFILES=debug docker compose up
COMPOSE_PROFILES=frontend,debug docker compose up

Auto-Activation

When you explicitly target a profiled service, Compose runs it regardless of profile activation:

docker compose run db-migrations         # Runs even without --profile tools

Critical constraint: If the targeted service has profiled dependencies, those dependencies MUST either share the same profile, be started separately, or have no profile assignment.

Extends and Include

Extends Directive

Inherits configuration from another service without including that service in the final project.

# From another file
services:
  web:
    extends:
      file: common-services.yml
      service: webapp
    ports:
      - "8080:80"

# Within the same file
services:
  web:
    extends: webapp

Locally-defined attributes ALWAYS override extended values. Relative paths in extended files are automatically converted.

Include Directive

Imports entire Compose files as independent application models:

include:
  - my-compose-include.yaml
  - path:
      - third-party/compose.yaml
      - override.yaml                    # Paired override
  - oci://docker.io/user/app:latest      # Remote OCI source

Each included file resolves paths relative to its own directory. Direct resource conflicts between included files cause an error. Works recursively.

Multiple Compose Files

Override Convention

By default, Compose loads compose.yaml THEN compose.override.yaml automatically. No -f flag needed.

# Explicit multi-file (processed left-to-right, later overrides earlier)
docker compose -f compose.yaml -f compose.prod.yaml up
docker compose -f compose.yaml -f compose.admin.yaml run backup_db

Override files need NOT be complete or valid standalone Compose files. They can be fragments.

ALWAYS resolve paths relative to the first (base) file.

Remote Compose Files

# OCI Registry
docker compose -f oci://registry.example.com/project:latest up

# Git Repository
docker compose -f https://github.com/user/repo.git up
docker compose -f https://github.com/user/repo.git@v1.0.0 up
docker compose -f git@github.com:user/repo.git#main:path/to/compose.yaml up

Compose Watch

Configuration

services:
  web:
    build: .
    develop:
      watch:
        - action: sync
          path: ./web
          target: /src/web
          initial_sync: true
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json
        - action: sync+restart
          path: ./proxy/nginx.conf
          target: /etc/nginx/conf.d/default.conf

Action Types

Action	Behavior	Use Case
`sync`	Syncs host files to container path	Hot reload frameworks (React, Vue)
`rebuild`	Builds new image, replaces container	Dependency changes, compiled languages
`sync+restart`	Syncs files then restarts container	Config file changes (nginx.conf, .ini)

Usage

docker compose up --watch              # Combined with logs
docker compose watch                   # Separate from logs

Constraints

Works ONLY with services that have a build attribute, NEVER with pre-built image-only services
Container image MUST contain stat, mkdir, rmdir utilities
Container USER MUST have write permissions to target paths
ALWAYS ignore large directories (e.g., node_modules/) for performance
Does NOT support glob patterns in path definitions

Compose CLI Workflow

Essential Commands

Command	Purpose
`docker compose up -d`	Create and start containers (detached)
`docker compose down`	Stop and remove containers and networks
`docker compose build`	Build or rebuild service images
`docker compose ps`	List running containers
`docker compose logs -f`	Follow container log output
`docker compose exec <svc> <cmd>`	Run command in running container
`docker compose run <svc> <cmd>`	Run one-off command on a service
`docker compose config`	Validate and display resolved config
`docker compose --dry-run up`	Preview changes without executing

.env File Rules

Default location: .env next to compose.yaml
Override with: docker compose --env-file ./config/.env.dev up
Multiple files: docker compose --env-file .env --env-file .env.override up
Later files override earlier files
Lines starting with # are comments
Single-quoted values are literal (no interpolation)
Double-quoted values support escape sequences: \n, \r, \t, \\

Decision Trees

Which Multi-File Strategy to Use?

Need to customize a third-party Compose file?
├── YES → Use `include` with paired override file
└── NO
    ├── Need to share base service config across services?
    │   └── YES → Use `extends` directive
    └── Need environment-specific overrides (dev/prod)?
        ├── YES, two environments → Use compose.override.yaml (auto-loaded)
        └── YES, multiple → Use explicit -f flag with per-environment files

Which Watch Action to Use?

What changed?
├── Source code (interpreted language) → sync
├── Config file (needs process restart) → sync+restart
└── Dependencies or compiled code → rebuild

Reference Links

references/patterns.md -- Profile patterns, merge rules, extend patterns, watch configuration
references/examples.md -- Dev/prod workflow, multi-file setup, profile-based optional services
references/anti-patterns.md -- Workflow mistakes and corrections