Docker Compose container orchestration and management. Manage multi-container applications, services, networks, and volumes. Use for local development, testing, and orchestration of containerized applications.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
docker-compose
description
Docker Compose container orchestration and management. Manage multi-container applications, services, networks, and volumes. Use for local development, testing, and orchestration of containerized applications.
version
1.2.0
model
sonnet
invoked_by
both
user_invocable
true
tools
["Bash","Read","Glob"]
best_practices
["Prefer compose.yaml (canonical V2 name) over docker-compose.yml","Use `docker compose` (V2 plugin) never `docker-compose` (V1 binary)","Verify compose.yaml exists before operations","Use project names for isolation","Check service status before destructive operations","Avoid volume removal without confirmation","Review logs before restarting failed services","Define healthchecks on all stateful services","Use profiles for environment-specific services","Use watch + develop block for live development reloading"]
YAML: Use named volumes for DBs (postgres_data:/var/lib/postgresql/data). Use healthchecks (healthcheck: with test, interval, timeout, retries). One network default; reference services by name (e.g. http://api:3000). Use env_file or environment; keep secrets in secrets:.
Hacks:-f compose.yaml -f override.yaml merges files (later overrides). Use --project-name for isolation. Prefer build: context: . dockerfile: Dockerfile for dev; pin image tags in prod. Run docker compose config before up to catch errors.
Suggested hooks: Pre-up: docker compose config (validate). Post-down: optional cleanup. Use when devops or devops-troubleshooter is routed.
Workflows: Use with devops (primary), devops-troubleshooter (primary). Flow: validate compose → up/down/exec per task. See operations/incident-response for container debugging.
Overview
This skill provides comprehensive Docker Compose management, enabling AI agents to orchestrate multi-container applications, manage services, inspect logs, and troubleshoot containerized environments with progressive disclosure for optimal context usage.
Valid compose.yaml (preferred) or compose.yml / docker-compose.yml in project
Appropriate permissions for Docker socket access
Quick Reference
# List running services
docker compose ps
# View service logs
docker compose logs <service>
# Start services
docker compose up -d
# Stop services
docker compose down
# Rebuild services
docker compose build
# Execute command in container
docker compose exec <service> <command>
# Live development reloading (Compose Watch)
docker compose watch
# Start with a profile active
docker compose --profile debug up -d
# Validate merged config
docker compose config
2026 Feature Highlights
compose.yaml — Canonical Filename
Docker Compose V2 prefers compose.yaml (and compose.yml) over the legacy docker-compose.yml.
The version: top-level field is deprecated and should be omitted entirely in new files.
# compose.yaml (preferred — no version: field needed)services:web:build:.ports:-'8080:80'db:image:postgres:16-alpineenvironment:POSTGRES_PASSWORD:examplevolumes:-postgres_data:/var/lib/postgresql/datavolumes:postgres_data:
Compose Watch — Live Development Reloading
Compose Watch (GA as of Compose 2.22+) replaces the manual rebuild-restart cycle during development. Configure a develop.watch block per service. Three actions are available:
Action
Behavior
sync
Instantly copies changed files into the running container
rebuild
Triggers docker compose build + recreates the container
sync+restart
Syncs files then restarts the container process (no full rebuild)
services:api:build:.ports:-'3000:3000'develop:watch:# Sync source instantly — no rebuild needed for interpreted code-action:syncpath:./srctarget:/app/srcignore:-node_modules/# Rebuild when dependency manifest changes-action:rebuildpath:package.json# Restart only when config changes-action:sync+restartpath:./configtarget:/app/config
Start with:
# Watch mode (keeps output in foreground)
docker compose watch
# Or combined with up
docker compose up --watch
When to use each action:
sync — interpreted languages (Node.js, Python, Ruby) where the runtime picks up changes
sync+restart — config or template files that require a process restart but not a full rebuild
Profiles allow a single compose.yaml to serve multiple environments. Services without a profile always start. Services with profiles only start when that profile is activated.
services:# Always starts — no profileapi:build:.ports:-'3000:3000'depends_on:db:condition:service_healthydb:image:postgres:16-alpinehealthcheck:test: ['CMD-SHELL', 'pg_isready -U postgres']
interval:5stimeout:3sretries:5volumes:-db_data:/var/lib/postgresql/data# Only with --profile debugpgadmin:image:dpage/pgadmin4:latestprofiles: ['debug']
ports:-'5050:80'environment:PGADMIN_DEFAULT_EMAIL:admin@admin.comPGADMIN_DEFAULT_PASSWORD:admin# Only with --profile monitoringprometheus:image:prom/prometheus:latestprofiles: ['monitoring']
ports:-'9090:9090'grafana:image:grafana/grafana:latestprofiles: ['monitoring']
ports:-'3001:3000'volumes:db_data:
# Default: api + db only
docker compose up -d
# Debug: api + db + pgadmin
docker compose --profile debug up -d
# Monitoring: api + db + prometheus + grafana
docker compose --profile monitoring up -d
# Multiple profiles
docker compose --profile debug --profile monitoring up -d
# Via environment variable
COMPOSE_PROFILES=debug,monitoring docker compose up -d
The include top-level key (introduced in Compose 2.20) allows you to split large compose files into modular, team-owned pieces. Each included file is loaded with its own project directory context, resolving relative paths correctly.
# compose.yaml (root — application layer)include:-./infra/compose.yaml# DB, Redis, message broker-./monitoring/compose.yaml# Prometheus, Grafanaservices:api:build:.depends_on:-db# defined in infra/compose.yaml-redis# defined in infra/compose.yaml
include is recursive — included files can themselves include other files. Conflicts between resource names cause an error (no silent merging).
Healthcheck Best Practices
Always define healthchecks on stateful services so that depends_on: condition: service_healthy works correctly. Without healthchecks, dependent services may start before their dependency is ready.
services:db:image:postgres:16-alpinehealthcheck:test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
interval:10s# How often to checktimeout:5s# Time to wait for responseretries:5# Failures before marking unhealthystart_period:30s# Grace period during container startupredis:image:redis:7-alpinehealthcheck:test: ['CMD', 'redis-cli', 'ping']
interval:10stimeout:3sretries:3api:build:.depends_on:db:condition:service_healthy# waits until db passes healthcheckredis:condition:service_healthy
Healthcheck guidelines:
Use CMD (array form) not CMD-SHELL (string form) where possible — avoids shell injection risk
Use CMD-SHELL only when you need shell features (pg_isready, curl -f, etc.)
Set start_period for services with slow startup (JVM apps, first-run migrations)
Avoid curl in Alpine-based images unless explicitly installed; prefer wget -q --spider or native checks
Use multi-stage Dockerfiles to keep production images minimal and secure. Reference the specific build stage in compose.yaml for development.
# Dockerfile
# Stage 1: deps — install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci
# Stage 2: builder — compile/transpile
FROM deps AS builder
COPY . .
RUN npm run build
# Stage 3: runner — minimal production image
FROM node:20-alpine AS runner
RUN addgroup -g 1001 -S appgroup && adduser -S -u 1001 -G appgroup appuser
WORKDIR /app
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=deps --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD wget -q --spider http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]
# compose.yaml — dev targets the builder stage for faster iterationservices:api:build:context:.dockerfile:Dockerfiletarget:builder# Stop at builder stage in dev (includes devDeps)develop:watch:-action:syncpath:./srctarget:/app/srcignore:-node_modules/-action:rebuildpath:package.json
# compose.prod.yaml — production uses the full runner stageservices:api:build:context:.dockerfile:Dockerfiletarget:runner# Minimal, non-root production imagerestart:unless-stopped
Resource Limits (Best Practice)
Always define resource limits to prevent container resource exhaustion:
# 1. Ensure develop.watch blocks are configured in compose.yaml# 2. Start with watch mode (foreground, shows sync events)
docker compose watch
# 3. Or start detached then watch
docker compose up -d
docker compose watch --no-up
Troubleshoot a Failing Service
# 1. Check container status
docker compose ps --all
# 2. View service logs
docker compose logs --tail 200 failing-service
# 3. Inspect running processes
docker compose top failing-service
# 4. Check configuration
docker compose config
# 5. Restart the service
docker compose restart failing-service
# 6. If needed, recreate container
docker compose up -d --force-recreate failing-service
Update Service Images
# 1. Pull latest images
docker compose pull
# 2. Stop services
docker compose down
# 3. Rebuild if using custom Dockerfiles
docker compose build --pull
# 4. Start with new images
docker compose up -d
# 5. Verify services
docker compose ps
Debug Service Connectivity
# 1. Check running services
docker compose ps
# 2. Inspect port mappings
docker compose port web 80
docker compose port api 3000
# 3. Exec into container
docker compose exec web sh
# 4. Test connectivity (from inside container)
docker compose exec web curl api:3000/health
# 5. Check logs for errors
docker compose logs web api
Clean Up Environment
# 1. Stop all services
docker compose down
# 2. Remove orphaned containers
docker compose down --remove-orphans
# 3. View images
docker compose images
# 4. Clean up (manual - volume removal BLOCKED)# Volumes require manual cleanup with explicit confirmation
Use Profiles for Environment-Specific Services
# Development: default services only
docker compose up -d
# Development + debug tools
docker compose --profile debug up -d
# Start monitoring stack
docker compose --profile monitoring up -d
# Via env var (useful in CI)
COMPOSE_PROFILES=monitoring docker compose up -d
# Stop and clean a specific profile
docker compose --profile debug down
The skill uses progressive disclosure to minimize context usage:
Initial Load: Only metadata and tool names (~700 tokens)
Tool Invocation: Specific tool schema loaded on-demand (~100-150 tokens)
Result Streaming: Large outputs (logs) streamed incrementally
Context Cleanup: Old results cleared after use
Context Optimization:
Use --tail to limit log output
Use service filters to target specific containers
Prefer ps over ps --all for active services only
Use --since for time-bounded log queries
Troubleshooting
Skill Issues
Docker Compose not found:
# Check Docker Compose version
docker compose version
# V1 (docker-compose) is end-of-life — upgrade to V2# Docker Compose V2 is integrated into Docker CLI as a plugin
Permission denied:
# Add user to docker group (Linux)sudo usermod -aG docker $USER
newgrp docker
# Verify permissions
docker ps
cloud-devops-expert - Cloud platforms (AWS, GCP, Azure) and Terraform infrastructure
Iron Laws
ALWAYS use docker compose (V2 plugin) — never use docker-compose (V1 standalone), which is deprecated and will be removed.
NEVER include secrets or credentials directly in compose files or committed .env files — use external secret management or .env.example templates for documentation only.
ALWAYS define health checks on services that other services depend on — without health checks, dependent services start before their dependencies are actually ready.
NEVER expose a service port to the host unless it must be accessed from outside the compose network — unnecessary host port exposure increases attack surface.
ALWAYS specify resource limits (CPU and memory) on services intended for production — unlimited containers can starve other services and crash the host.
Anti-Patterns
Anti-Pattern
Why It Fails
Correct Approach
Using docker-compose V1 command
V1 is deprecated; missing V2 features (profiles, merge, watch) and will be removed
Use docker compose (space, not hyphen); verify docker compose version
Hardcoded secrets in compose file
Secrets committed to git are permanently exposed in history
Use environment variable references (${SECRET}) loaded from untracked .env
No health checks on database/cache services
App containers start before DB is ready; causes startup race conditions and crashes
Add healthcheck: with appropriate test commands; use depends_on: condition: service_healthy
Exposing all ports to host (0.0.0.0)
Services accessible from any network interface including public interfaces
Bind to 127.0.0.1 for dev; use internal networks for service-to-service communication
No restart policy
Containers stay down after crash or host reboot in production
Use restart: unless-stopped for services that should auto-recover
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md
After completing:
New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
