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)

| 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 | Run command in running container | | docker compose run | 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](references/patterns.md) -- Profile patterns, merge rules, extend patterns, watch configuration
• [references/examples.md](references/examples.md) -- Dev/prod workflow, multi-file setup, profile-based optional services
• [references/anti-patterns.md](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/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Docker-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.