interface:
  display_name: Docker Compose Patterns
  short_description: Patterns for robust, maintainable Docker Compose configurations.
  default_prompt: Use this skill when creating or modifying Docker Compose files.
policy:
  allow_implicit_invocation: true

# Common Compose Mistakes: Before and After

## 1. Missing health checks on database dependencies

### Bad

```yaml
services:
  web:
    build: .
    depends_on:
      - db
  db:
    image: postgres:17
```

`depends_on` without a condition only waits for the container to start, not for Postgres to accept connections. The web service will crash on startup.

### Good

```yaml
services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 10s
```

---

## 2. Using `latest` tag

### Bad

```yaml
services:
  cache:
    image: redis:latest
```

`latest` is mutable. Builds become non-reproducible and can break without warning.

### Good

```yaml
services:
  cache:
    image: redis:7
```

Pin to a specific major or minor version.

---

## 3. Hardcoded secrets in compose.yaml

### Bad

```yaml
services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: supersecretpassword123
```

Secrets in the Compose file end up in version control.

### Good

```yaml
services:
  db:
    image: postgres:17
    env_file:
      - .env
```

With `.env` containing `POSTGRES_PASSWORD=supersecretpassword123` and `.env` listed in `.gitignore`.

---

## 4. Bind mount for database data

### Bad

```yaml
services:
  db:
    image: postgres:17
    volumes:
      - ./pgdata:/var/lib/postgresql/data
```

Bind mounts for database storage cause permission issues and poor I/O performance on macOS and Windows.

### Good

```yaml
services:
  db:
    image: postgres:17
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:
```

Named volumes are managed by Docker and perform correctly on all platforms.

---

## 5. Legacy filename

### Bad

```
docker-compose.yml
```

### Good

```
compose.yaml
```

`compose.yaml` is the canonical filename. `docker-compose.yml` is legacy.

---

## 6. Development settings in the base Compose file

### Bad

A single `compose.yaml` with bind mounts, debug ports, and development environment variables mixed in with production settings.

### Good

Base `compose.yaml` with production-appropriate defaults. Development-only settings in `compose.override.yaml`, which Compose loads automatically:

```yaml
# compose.override.yaml
services:
  web:
    ports:
      - "9229:9229"
    environment:
      LOG_LEVEL: debug
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
```

---

## 7. No restart policy

### Bad

```yaml
services:
  web:
    image: myapp:1.0.0
```

Without a restart policy, the container stays down after a crash or host reboot.

### Good

```yaml
services:
  web:
    image: myapp:1.0.0
    restart: unless-stopped
```

# Development override — loaded automatically as compose.override.yaml
# Adds bind mounts, debug ports, and Compose Watch configuration
# Usage: save as compose.override.yaml alongside compose.yaml

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      target: development
    ports:
      - "9229:9229" # Debugger port (8080 is already in the base file)
    environment:
      NODE_ENV: development
      LOG_LEVEL: debug
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: ./package.json
        - action: sync+restart
          path: ./config
          target: /app/config

  db:
    ports:
      - "127.0.0.1:5432:5432" # Expose DB only to local tools

  cache:
    ports:
      - "127.0.0.1:6379:6379" # Expose Redis only to local tools

# Complete multi-service web application
# Stack: Application + PostgreSQL + Redis
# Run: docker compose up -d

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD:-secret}@db:5432/myapp
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-secret}
      POSTGRES_DB: myapp
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 10s
    restart: unless-stopped

  cache:
    image: redis:7
    volumes:
      - cache-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 5s
    restart: unless-stopped

volumes:
  db-data:
  cache-data:

# Verification Runbook for Generated Compose Files

Run these checks against every generated `compose.yaml` before considering it complete.

## 1. Syntax and schema validation

Run the bundled script from the project root (the directory that contains `compose.yaml`), with the script path resolved under the skill directory:

```bash
bash "<skill-dir>/scripts/verify-compose.sh" [--help]
```

Replace `<skill-dir>` with the absolute path of this skill's directory, the folder that contains `SKILL.md` and this `checks/` folder. Do not change into the skill directory to run it; the script validates the Compose project in the current directory.

Exit status is `0` when the Compose configuration is valid or help is requested, the non-zero status from `docker compose config --quiet` when validation fails, and `2` for invalid arguments.

To run the underlying validation directly:

```bash
docker compose config --quiet
```

This parses and validates the Compose file without printing the resolved configuration. It still resolves variables and reads service `env_file` files. If it exits non-zero, fix the reported errors before proceeding.

Plain `docker compose config` renders interpolated and `env_file` credentials. Do not capture that output in CI logs or agent transcripts. If inspecting the rendered configuration is necessary, use a separate copy with dummy credentials and review it locally. `--quiet` suppresses the configuration dump, not warnings or errors; diagnostics may still contain sensitive details.

## 2. Health check presence

Verify that every database, cache, or message broker service has a `healthcheck` defined. Review the Compose source files, including overrides, and confirm these services include `healthcheck.test`, `healthcheck.interval`, `healthcheck.timeout`, `healthcheck.retries`, and `healthcheck.start_period`. For rendered inspection, follow the dummy-credential precaution above.

Services that must have health checks:

- PostgreSQL, MySQL, MariaDB
- Redis, Memcached
- MongoDB
- RabbitMQ, Kafka
- Elasticsearch

## 3. Dependency ordering

For every service with `depends_on`:

- Confirm `condition: service_healthy` is set for infrastructure dependencies.
- Confirm the referenced service has a matching `healthcheck`.
- Confirm no circular dependencies exist (Compose will reject these, but verify intent).

## 4. Volume definitions

- Every volume referenced in a service's `volumes:` list that uses the `name:/path` format must have a corresponding entry in the top-level `volumes:` key.
- Database services must use named volumes, not bind mounts, for data directories.
- Bind mounts should appear only in development override files.

## 5. Environment variables and secrets

- No plaintext passwords, API keys, or tokens appear directly in `compose.yaml`.
- Sensitive values use `env_file:` or Docker secrets.
- If `.env` is referenced, confirm `.env` is in `.gitignore`.

## 6. Published ports and host mounts

- Published datastore ports bind to loopback unless remote host access is explicitly required.
- Services do not mount the Docker socket from `/var/run/docker.sock` or `/run/docker.sock`.

## 7. Image tags

- No service uses the `latest` tag or omits the tag entirely.
- All image references include an explicit version.

## 8. Runtime verification

After `docker compose up -d`:

```bash
# Check all services are running and healthy
docker compose ps

# Verify health check status specifically
docker inspect --format='{{.State.Health.Status}}' <container_name>

# Check logs for startup errors
docker compose logs --tail=50

# Verify inter-service connectivity
docker compose exec web ping -c 1 db
```

## 9. File naming

- The file is named `compose.yaml`, not `docker-compose.yml` or `docker-compose.yaml`.
- Development overrides are in `compose.override.yaml`.

# Service Dependencies and Startup Ordering

## depends_on conditions

The `depends_on` key supports three conditions:

| Condition | Meaning |
|---|---|
| `condition: service_started` | Waits only for the container to start (default if no condition specified). |
| `condition: service_healthy` | Waits for the container's health check to pass. |
| `condition: service_completed_successfully` | Waits for the container to run and exit with code 0. Useful for init/migration containers. |

Always use `condition: service_healthy` for infrastructure services (databases, caches, message brokers). The `service_started` condition is insufficient because a container can be running before the process inside is accepting connections.

## Health check patterns for common services

### PostgreSQL

```yaml
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]
  interval: 5s
  timeout: 3s
  retries: 3
  start_period: 10s
```

### MySQL / MariaDB

```yaml
healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
  interval: 5s
  timeout: 3s
  retries: 3
  start_period: 20s
```

MySQL can take longer to initialize on first run. Use a `start_period` of 20s or more.

### Redis

```yaml
healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 5s
  timeout: 3s
  retries: 3
  start_period: 5s
```

### MongoDB

```yaml
healthcheck:
  test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
  interval: 5s
  timeout: 3s
  retries: 3
  start_period: 10s
```

### RabbitMQ

```yaml
healthcheck:
  test: ["CMD", "rabbitmq-diagnostics", "check_running"]
  interval: 10s
  timeout: 5s
  retries: 3
  start_period: 30s
```

RabbitMQ has a longer startup time. Set `start_period` to at least 30s.

### Elasticsearch

```yaml
healthcheck:
  test: ["CMD-SHELL", "curl -fs http://localhost:9200/_cluster/health || exit 1"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 30s
```

## Init containers pattern

Use `service_completed_successfully` for one-shot tasks like database migrations:

```yaml
services:
  migrate:
    image: myapp:1.2.0
    command: ["./manage.py", "migrate"]
    depends_on:
      db:
        condition: service_healthy

  web:
    image: myapp:1.2.0
    depends_on:
      db:
        condition: service_healthy
      migrate:
        condition: service_completed_successfully
```

This ensures migrations complete before the web service starts.

## Restart behavior and dependencies

`depends_on` only governs initial startup ordering. It does not re-trigger if a dependency restarts. For runtime resilience:

- Configure application-level retry/reconnect logic.
- Use `restart: unless-stopped` so services recover from transient failures.
- Do not chain long dependency trees. Keep the graph shallow — deep chains increase total startup time and fragility.

# Volumes and Networks

## Volume types

### Named volumes

Use named volumes for data that must persist across container recreations:

```yaml
services:
  db:
    image: postgres:17
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:
```

Named volumes are managed by Docker. They survive `docker compose down` (but not `docker compose down -v`, which deletes them and their data irreversibly). Never run `down -v` to work around a startup or connectivity problem — get explicit user confirmation first.

### Bind mounts

Use bind mounts to sync host directories into containers. Appropriate for development-time source code mounting only:

```yaml
services:
  web:
    build: .
    volumes:
      - ./src:/app/src
```

Do not use bind mounts for database data — they cause permission issues and poor performance on macOS and Windows.

### Anonymous volumes

Avoid anonymous volumes (volumes with no name and no host path). They are hard to track and clean up. Always use named volumes.

### tmpfs mounts

Use `tmpfs` for ephemeral scratch data that should not persist:

```yaml
services:
  app:
    image: myapp:1.0.0
    tmpfs:
      - /tmp
      - /app/cache
```

## Volume mount flags

- Use `:ro` to mount volumes as read-only when the container should not write to them.
- Use `:cached` or `:delegated` on macOS only when performance requires it and data consistency tradeoffs are acceptable. Prefer Compose Watch (`develop.watch`) over bind mounts with performance flags.

## Volume patterns

### Excluding node_modules from bind mounts

When bind-mounting a Node.js project, exclude `node_modules` with an anonymous volume to prevent host dependencies from overwriting container dependencies:

```yaml
services:
  web:
    build: .
    volumes:
      - ./:/app
      - /app/node_modules
```

This mounts the project root but keeps the container's own `node_modules` intact.

### Sharing data between services

Use a named volume to share files between services:

```yaml
services:
  generator:
    image: myapp:1.0.0
    volumes:
      - shared-data:/output

  consumer:
    image: nginx:1.27
    volumes:
      - shared-data:/usr/share/nginx/html:ro

volumes:
  shared-data:
```

## Networks

### Default network

Compose creates a default network for each project. All services join it automatically. Services can reach each other by service name as the hostname. For most single-application stacks, the default network is sufficient.

### Custom networks for isolation

Use custom networks when you need to isolate groups of services:

```yaml
services:
  web:
    image: myapp:1.0.0
    networks:
      - frontend
      - backend

  db:
    image: postgres:17
    networks:
      - backend

  proxy:
    image: nginx:1.27
    networks:
      - frontend

networks:
  frontend:
  backend:
```

In this example, `proxy` cannot reach `db` directly because they share no network. `web` bridges both.

### External networks

Use `external: true` to reference a network created outside this Compose file:

```yaml
networks:
  shared:
    external: true
    name: my-shared-network
```

This is useful when multiple Compose projects need to communicate.

### Network aliases

Use aliases to give a service additional hostnames on a specific network:

```yaml
services:
  db:
    image: postgres:17
    networks:
      backend:
        aliases:
          - database
          - postgres
```

Other services on the `backend` network can reach this service as `db`, `database`, or `postgres`.

#!/usr/bin/env bash
# Verify Compose configuration. Run from the project root.
# Usage: bash "<skill-dir>/scripts/verify-compose.sh" [--help]
# <skill-dir> is the directory that contains this skill's SKILL.md.
set -euo pipefail

usage() {
    echo "Usage: bash \"<skill-dir>/scripts/verify-compose.sh\" [--help]"
    echo "Run from the project root; <skill-dir> is the directory that contains this skill's SKILL.md."
    echo "Validates compose.yaml with docker compose config --quiet (no rendered configuration)."
}

if [[ "${1:-}" == "--help" && $# == 1 ]]; then
    usage
    exit 0
fi

if (( $# != 0 )); then
    usage >&2
    exit 2
fi

docker compose config --quiet