Docker Compose Skill Skill

Docker Compose Skill

Installation

The skill invokes docker compose. Easiest: install Docker Desktop (includes Docker Engine + Compose):

Windows: Docker Desktop for Windows (WSL 2 or Hyper-V)
Mac: Docker Desktop for Mac (Apple Silicon or Intel)
Linux: Docker Desktop for Linux or Docker Engine + Compose plugin from Docker's repo

Verify: docker compose version

Cheat Sheet & Best Practices

Commands: docker compose up -d / down; docker compose ps / logs -f <service>; docker compose exec <service> sh; docker compose build --no-cache; docker compose -f compose.prod.yaml config — validate.

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.

Certifications & Training

Docker Certified Associate (DCA): Orchestration 25%, Image/Registry 20%, Install/Config 15%, Networking 15%, Security 15%, Storage 10%. Free: Official DCA Study Guide, Coursera DCA Prep (audit). Skill data: Compose YAML (services, volumes, networks, healthchecks), CLI (up/down/ps/logs/exec).

Hooks & Workflows

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.

Context Savings: ~92% reduction

MCP Mode: ~25,000 tokens always loaded (multiple tools + schemas)
Skill Mode: ~700 tokens metadata + on-demand loading

When to Use

Managing local development environments
Orchestrating multi-container applications
Debugging service connectivity and networking
Monitoring container logs and health
Building and updating service images
Testing containerized application stacks
Troubleshooting service failures
Managing application lifecycle (start, stop, restart)

Requirements

Docker Engine installed and running
Docker Compose V2 (docker compose plugin — V1 docker-compose is end-of-life)
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-alpine
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  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: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        # Rebuild when dependency manifest changes
        - action: rebuild
          path: package.json
        # Restart only when config changes
        - action: sync+restart
          path: ./config
          target: /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
rebuild — dependency manifest changes (package.json, requirements.txt, go.mod)

Profiles — Environment-Specific Services

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 profile
  api:
    build: .
    ports:
      - '3000:3000'
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  # Only with --profile debug
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles: ['debug']
    ports:
      - '5050:80'
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@admin.com
      PGADMIN_DEFAULT_PASSWORD: admin

  # Only with --profile monitoring
  prometheus:
    image: prom/prometheus:latest
    profiles: ['monitoring']
    ports:
      - '9090:9090'

  grafana:
    image: grafana/grafana:latest
    profiles: ['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

Profile naming rules: [a-zA-Z0-9][a-zA-Z0-9_.-]+ — lowercase kebab-case recommended.

Include — Composable Configs

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, Grafana

services:
  api:
    build: .
    depends_on:
      - db # defined in infra/compose.yaml
      - redis # defined in infra/compose.yaml

# infra/compose.yaml (infrastructure layer — owned by platform team)
services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  db_data:

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-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
      interval: 10s # How often to check
      timeout: 5s # Time to wait for response
      retries: 5 # Failures before marking unhealthy
      start_period: 30s # Grace period during container startup

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy # waits until db passes healthcheck
      redis:
        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
For HTTP services: test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/health || exit 1"]

Multi-Stage Build Pattern

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 iteration
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: builder # Stop at builder stage in dev (includes devDeps)
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json

# compose.prod.yaml — production uses the full runner stage
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: runner # Minimal, non-root production image
    restart: unless-stopped

Resource Limits (Best Practice)

Always define resource limits to prevent container resource exhaustion:

services:
  api:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    restart: unless-stopped

Tools

The skill provides 15 tools across service management, monitoring, build operations, and troubleshooting categories:

Service Management (5 tools)

up

Start services defined in compose.yaml.

| Parameter | Type | Description | Default | | ---------------- | ------- | ---------------------------- | -------------- | | detached | boolean | Run in detached mode | true | | build | boolean | Build images before starting | false | | force_recreate | boolean | Recreate containers | false | | project_name | string | Project name override | directory name | | services | array | Specific services to start | all services | | profiles | array | Profiles to activate | none | | watch | boolean | Enable Compose Watch mode | false |

Example:

docker compose up -d
docker compose up --build
docker compose up web api
docker compose --profile debug up -d
docker compose up --watch

Safety: Requires confirmation for production environments.

down

Stop and remove containers, networks, volumes.

| Parameter | Type | Description | Default | | ---------------- | ------- | -------------------------- | -------------- | | volumes | boolean | Remove volumes (BLOCKED) | false | | remove_orphans | boolean | Remove orphaned containers | false | | project_name | string | Project name override | directory name |

Example:

docker compose down
docker compose down --remove-orphans

Safety: Volume removal (-v flag) is BLOCKED by default. Requires confirmation.

start

Start existing containers without recreating them.

| Parameter | Type | Description | Default | | -------------- | ------ | -------------------------- | -------------- | | services | array | Specific services to start | all services | | project_name | string | Project name override | directory name |

Example:

docker compose start
docker compose start web

stop

Stop running containers without removing them.

| Parameter | Type | Description | Default | | -------------- | ------ | -------------------------- | -------------- | | timeout | number | Shutdown timeout (seconds) | 10 | | services | array | Specific services to stop | all services | | project_name | string | Project name override | directory name |

Example:

docker compose stop
docker compose stop --timeout 30 web

restart

Restart services (stop + start).

| Parameter | Type | Description | Default | | -------------- | ------ | ---------------------------- | -------------- | | timeout | number | Shutdown timeout (seconds) | 10 | | services | array | Specific services to restart | all services | | project_name | string | Project name override | directory name |

Example:

docker compose restart
docker compose restart api

Status & Logs (3 tools)

ps

List containers with status information.

| Parameter | Type | Description | Default | | -------------- | ------- | --------------------------------------- | -------------- | | all | boolean | Show all containers (including stopped) | false | | services | array | Filter by services | all services | | project_name | string | Project name override | directory name |

Example:

docker compose ps
docker compose ps --all

Output Fields: NAME, IMAGE, STATUS, PORTS

logs

View service logs with streaming support.

| Parameter | Type | Description | Default | | -------------- | ------- | ---------------------------------- | -------------- | | services | array | Services to view logs for | all services | | follow | boolean | Follow log output (stream) | false | | tail | number | Number of lines to show | 100 | | timestamps | boolean | Show timestamps | false | | since | string | Show logs since timestamp/duration | none | | project_name | string | Project name override | directory name |

Example:

docker compose logs web
docker compose logs --tail 50 --follow api
docker compose logs --since "2026-01-01T10:00:00"

Note: Follow mode automatically terminates after 60 seconds to prevent indefinite streaming.

top

Display running processes in containers.

| Parameter | Type | Description | Default | | -------------- | ------ | --------------------- | -------------- | | services | array | Services to inspect | all services | | project_name | string | Project name override | directory name |

Example:

docker compose top
docker compose top web

Output: Process list with PID, USER, TIME, COMMAND

Build & Images (3 tools)

build

Build or rebuild service images.

| Parameter | Type | Description | Default | | -------------- | ------- | ------------------------- | -------------- | | no_cache | boolean | Build without cache | false | | pull | boolean | Pull newer image versions | false | | parallel | boolean | Build in parallel | true | | services | array | Services to build | all services | | project_name | string | Project name override | directory name |

Example:

docker compose build
docker compose build --no-cache web
docker compose build --pull

Safety: Requires confirmation for no-cache builds (resource-intensive).

pull

Pull service images from registry.

| Parameter | Type | Description | Default | | ---------------------- | ------- | ---------------------- | -------------- | | ignore_pull_failures | boolean | Continue if pull fails | false | | services | array | Services to pull | all services | | project_name | string | Project name override | directory name |

Example:

docker compose pull
docker compose pull web api

Safety: Requires confirmation for production environments.

images

List images used by services.

| Parameter | Type | Description | Default | | -------------- | ------ | --------------------- | -------------- | | project_name | string | Project name override | directory name |

Example:

docker compose images

Output Fields: CONTAINER, REPOSITORY, TAG, IMAGE ID, SIZE

Execution (2 tools)

exec

Execute a command in a running container.

| Parameter | Type | Description | Required | | -------------- | ------ | --------------------- | ----------------- | | service | string | Service name | Yes | | command | array | Command to execute | Yes | | user | string | User to execute as | container default | | workdir | string | Working directory | container default | | env | object | Environment variables | none | | project_name | string | Project name override | directory name |

Example:

docker compose exec web bash
docker compose exec -u root api ls -la /app
docker compose exec db psql -U postgres

Safety:

Destructive commands (rm -rf, dd, mkfs) are BLOCKED
Root user execution requires confirmation
Default timeout: 30 seconds

run

Run a one-off command in a new container.

| Parameter | Type | Description | Default | | -------------- | ------- | --------------------------- | ----------------- | | service | string | Service to run | Required | | command | array | Command to execute | service default | | rm | boolean | Remove container after run | true | | no_deps | boolean | Don't start linked services | false | | user | string | User to execute as | container default | | env | object | Environment variables | none | | project_name | string | Project name override | directory name |

Example:

docker compose run --rm web npm test
docker compose run --no-deps api python manage.py migrate

Safety: Requires confirmation for commands that modify data.

Configuration (2 tools)

config

Validate and view the Compose file configuration.

| Parameter | Type | Description | Default | | ----------------------- | ------- | -------------------------- | -------------- | | resolve_image_digests | boolean | Pin image tags to digests | false | | no_interpolate | boolean | Don't interpolate env vars | false | | project_name | string | Project name override | directory name |

Example:

docker compose config
docker compose config --resolve-image-digests

Output: Parsed and merged Compose configuration

port

Print the public port binding for a service port.

| Parameter | Type | Description | Required | | -------------- | ------ | --------------------- | -------------- | | service | string | Service name | Yes | | private_port | number | Container port | Yes | | protocol | string | Protocol (tcp/udp) | tcp | | project_name | string | Project name override | directory name |

Example:

docker compose port web 80
docker compose port db 5432

Output: <host>:<port> binding

Common Workflows

Start a Development Environment

# 1. Validate configuration
docker compose config

# 2. Pull latest images
docker compose pull

# 3. Build custom images
docker compose build

# 4. Start services in detached mode
docker compose up -d

# 5. Check service status
docker compose ps

# 6. View logs
docker compose logs --tail 100

Live Development with Compose Watch

# 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

Configuration

Environment Variables

| Variable | Description | Default | | ------------------------ | --------------------------------- | ------------------------------ | | COMPOSE_PROJECT_NAME | Default project name | directory name | | COMPOSE_FILE | Compose file path | compose.yaml | | COMPOSE_PROFILES | Comma-separated active profiles | (none) | | COMPOSE_PATH_SEPARATOR | Path separator for multiple files | : (Linux/Mac), ; (Windows) | | DOCKER_HOST | Docker daemon socket | unix:///var/run/docker.sock | | COMPOSE_HTTP_TIMEOUT | HTTP timeout for API calls | 60 | | COMPOSE_PARALLEL_LIMIT | Max parallel operations | unlimited |

Setup

Install Docker Engine:

# macOS
brew install --cask docker

# Linux (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Windows
# Download Docker Desktop from docker.com

Verify Docker Compose:

# Check Docker version
docker --version

# Check Compose version (must be V2, e.g. 2.24+)
docker compose version

Create compose.yaml (no version: field — V2 does not require it):

services:
  web:
    build: .
    ports:
      - '8080:80'
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 10s
      timeout: 5s
      retries: 5

Test the skill:

docker compose config
docker compose ps

Safety Features

Blocked Operations

The following operations are BLOCKED by default to prevent accidental data loss:

Volume removal: docker compose down -v (BLOCKED - requires manual confirmation)
Full cleanup: docker compose down -v --rmi all (BLOCKED - extremely destructive)
Destructive exec: rm -rf, dd, mkfs, sudo rm inside containers (BLOCKED)
Force removal: docker compose rm -f (BLOCKED - use stop then rm)

Confirmation Required

These operations require explicit confirmation:

Building with --no-cache (resource-intensive)
Pulling images in production environments
Starting services with --force-recreate
Executing commands as root user
Running commands that modify databases
Stopping services with very short timeouts

Auto-Terminating Operations

The following operations auto-terminate to prevent resource issues:

Log following (--follow): 60-second timeout
Service execution (exec): 30-second timeout
One-off commands (run): 60-second timeout

Error Handling

Common Errors:

| Error | Cause | Fix | | --------------------------------- | --------------------- | ----------------------------------------------- | | docker: command not found | Docker not installed | Install Docker Engine | | Cannot connect to Docker daemon | Docker not running | Start Docker service | | network ... not found | Network cleanup issue | Run docker compose down then up | | port is already allocated | Port conflict | Change port mapping or stop conflicting service | | no configuration file provided | Missing compose file | Create compose.yaml | | service ... must be built | Image not built | Run docker compose build | | service unhealthy | Healthcheck failing | Check docker compose logs <service> | | include path not found | Missing included file | Verify paths in include: block |

Recovery:

Validate configuration: docker compose config
Check Docker status: docker info
View service logs: docker compose logs
Force recreate: docker compose up -d --force-recreate
Clean restart: docker compose down && docker compose up -d

Integration with Agents

This skill integrates with the following agents:

Primary Agents

devops: Local development, CI/CD integration, container orchestration
developer: Application development, testing, debugging

Secondary Agents

qa: Integration testing, test environment setup
incident-responder: Debugging production issues, service recovery
cloud-integrator: Cloud deployment, migration to Kubernetes
performance-engineer: Performance testing, resource optimization

Progressive Disclosure

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

Compose file issues:

# Validate syntax
docker compose config

# Check for errors (quiet mode — exit code only)
docker compose config -q

# View resolved configuration
docker compose config --resolve-image-digests

Network issues:

# List networks
docker network ls

# Remove unused networks
docker network prune

# Recreate services
docker compose down
docker compose up -d

Healthcheck failures:

# Inspect healthcheck status
docker inspect <container_id> | grep -A 10 Health

# View healthcheck output
docker compose logs <service>

# Manually run the healthcheck command
docker compose exec <service> pg_isready -U postgres

Compose Watch not syncing:

# Verify develop.watch block is present in compose.yaml
docker compose config | grep -A 20 develop

# Ensure Compose version is 2.22+
docker compose version

# Watch requires build: attribute (not image: only)

Performance Considerations

Build caching: Use layer caching for faster builds; avoid --no-cache unless necessary
Multi-stage builds: Dramatically reduce production image size (often 80%+)
Parallel operations: Docker Compose V2 parallelizes by default; use COMPOSE_PARALLEL_LIMIT to control
Resource limits: Define CPU/memory limits in compose file to prevent resource exhaustion
Log rotation: Use logging drivers to prevent disk space issues
Volume cleanup: Regularly clean unused volumes (requires manual confirmation)
Compose Watch vs bind mounts: Prefer develop.watch for cross-platform development; bind mounts have I/O performance issues on macOS/Windows

Docker Compose Documentation: https://docs.docker.com/compose/
Compose File Reference: https://docs.docker.com/compose/compose-file/
Compose Watch Docs: https://docs.docker.com/compose/how-tos/file-watch/
Compose Profiles Docs: https://docs.docker.com/compose/how-tos/profiles/
Compose Include Docs: https://docs.docker.com/compose/how-tos/multiple-compose-files/include/
Docker CLI: https://docs.docker.com/engine/reference/commandline/cli/
Kubernetes Migration: .claude/skills/kubernetes-flux/ (Kubernetes orchestration)

Sources

Related Skills

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.

Agent Skills: Docker Compose Skill

Install this agent skill to your local

Skill Files