docker-compose

Docker Compose

Use this skill for the whole Compose lifecycle: model the application, validate the resolved configuration, start or update services, inspect runtime state, and diagnose failures. Prefer the current Compose Specification. Do not add a top-level version key to new files: it is obsolete and does not select a schema.

Operating loop

1. Discover the Compose file(s), project directory, env files, profiles, external resources, and whether the task is development, CI, staging, or production.
2. Model the application with services, named volumes for durable state, explicit networks for isolation, secrets for sensitive files, and profiles for optional services.
3. Resolve before running:

   docker compose -f compose.yaml config --quiet
   docker compose -f compose.yaml config
   docker compose -f compose.yaml config --services
   

4. Operate with the narrowest command: up -d SERVICE, restart SERVICE, run --rm SERVICE COMMAND, or exec SERVICE COMMAND. Avoid down -v unless data deletion is intentional and confirmed.
5. Verify with ps, health status, logs, an in-container check, and the externally published endpoint where applicable.
6. Diagnose in order: resolved model → container state → logs → healthcheck → network membership/DNS → mounts/permissions → image/build architecture → host resources.

Decision rules

• depends_on controls creation order, not readiness. Use a real healthcheck plus condition: service_healthy; use service_completed_successfully for migrations or jobs. Do not use sleep as readiness logic.
• Containers reach sibling services by service name and container port (db:5432), not host-published ports or container IPs.
• Use the default network for simple projects. Use separate networks to isolate tiers, internal: true for a network with no external gateway, and an explicitly named external: true network only when it is created outside the project.
• Use bind mounts for source/configuration during development, named volumes for state, and read-only mounts for immutable inputs. Treat host-path mounts as platform-sensitive.
• Put credentials in Compose secrets or an external secret manager, not in images, Git, or ordinary environment variables. Grant each secret only to services that need it. Compose secrets are mounted at /run/secrets/<name>.
• Use profiles for optional tools such as debugging, migrations, observability, or GPU workloads. Core services should have no profile.
• Resolve interpolation explicitly. Shell variables override --env-file, which overrides the project .env; use ${REQUIRED:?explain} for mandatory values and $$ for a literal dollar sign. For example, write test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"] when the container shell, not Compose, must expand the variable. Check with docker compose config --environment.
• In multi-file merges, later files are applied to the base. Relative paths resolve from the first/base file. Inspect the result with docker compose config; use !reset or !override when ordinary merge behavior is not what you want.
• Compose Watch is for services built from local source. Use sync for hot-reloadable source, sync+restart for configuration, and rebuild for dependency or image changes. The container user must be able to write to the target path.
• Treat deploy fields as implementation-dependent. Verify what the target Compose implementation enforces; the specification explicitly allows partial support.