Docker Impl Compose Workflows

docker-impl-compose-workflows

Quick Reference

Compose File Search Order

Compose searches for files in this order:

1. compose.yaml (preferred)
2. compose.yml
3. docker-compose.yaml
4. 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)

Variable Interpolation Syntax

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)

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

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

.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

Official Sources

• https://docs.docker.com/compose/how-tos/environment-variables/
• https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/
• https://docs.docker.com/compose/how-tos/environment-variables/envvars-precedence/
• https://docs.docker.com/compose/how-tos/profiles/
• https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/
• https://docs.docker.com/compose/how-tos/multiple-compose-files/extends/
• https://docs.docker.com/compose/how-tos/multiple-compose-files/include/
• https://docs.docker.com/compose/how-tos/file-watch/
• https://docs.docker.com/reference/cli/docker/compose/