Skip to content
Skills Library
DevOps & cloud · Building & coding

docker-compose

/docker-compose

Use this skill when authoring or editing Docker Compose files (compose.yaml / docker-compose.yml), running multi-container stacks, or containerizing a Drupal/PHP application — e.g. "set up a local Drupal stack with nginx and MariaDB", "add Redis to my compose file", "why won't my containers start", "split dev and prod compose configuration". Also trigger for compose commands (up, down, logs, exec, watch) and healthcheck/dependency issues between services.

Licence
MIT
Last repository change
26.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use this skill when authoring or editing Docker Compose files (compose.yaml / docker-compose.yml), running multi-container stacks, or containerizing a Drupal/PHP application — e.g. "set up a local Drupal stack with nginx and MariaDB", "add Redis to my compose file", "why won't my containers start", "split dev and prod compose configuration". Also trigger for compose commands (up, down, logs, exec, watch) and healthcheck/dependency issues between services.

Triggers from the description

set up a local Drupal stack with nginx and MariaDBadd Redis to my compose filewhy wonsplit dev and prod compose configuration
Original author description

Use this skill when authoring or editing Docker Compose files (compose.yaml / docker-compose.yml), running multi-container stacks, or containerizing a Drupal/PHP application — e.g. "set up a local Drupal stack with nginx and MariaDB", "add Redis to my compose file", "why won't my containers start", "split dev and prod compose configuration". Also trigger for compose commands (up, down, logs, exec, watch) and healthcheck/dependency issues between services.

How it works

  1. compose.yaml essentials
  2. Common commands
  3. Dev vs prod configuration
  4. Best practices
  5. Troubleshooting
Original SKILL.md headings · 159 lines, 677 words
SKILL.md preview
---
name: docker-compose
description: >
  Use this skill when authoring or editing Docker Compose files (compose.yaml /
  docker-compose.yml), running multi-container stacks, or containerizing a
  Drupal/PHP application — e.g. "set up a local Drupal stack with nginx and
  MariaDB", "add Redis to my compose file", "why won't my containers start",
  "split dev and prod compose configuration". Also trigger for compose
  commands (up, down, logs, exec, watch) and healthcheck/dependency issues
  between services.
---

# Docker Compose Skill

Docker Compose defines and runs multi-container applications from a single
`compose.yaml` file. This skill covers authoring the file, operating the
stack, and structuring configuration for development vs production, with a
typical Drupal stack (php-fpm, nginx, MariaDB, Redis) as the working example.

---

## compose.yaml essentials

- The canonical filename is `compose.yaml` (`docker-compose.yml` still works).
- **Do not add a top-level `version:` key** — it is obsolete and ignored by
  Compose v2; linters flag it.
- Services, networks, and volumes are declared at the top level.

### Drupal stack example

```yaml
services:
  php:
    build:
      context: .
      dockerfile: docker/php/Dockerfile
    volumes:
      - ./:/var/www/html
      - drupal-files:/var/www/html/web/sites/default/files
    environment:
      DRUPAL_DB_HOST: db
      DRUPAL_DB_NAME: drupal
      DRUPAL_DB_USER: drupal
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - ./:/var/www/html:ro
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - php

  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: drupal
      MARIADB_USER: drupal
      MARIADB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:?set DB_ROOT_PASSWORD in .env}
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine

volumes:
  db-data:
  drupal-files:
```

Key points illustrated:

- **`depends_on` with `condition: service_healthy`** — Drupal installs and
  `drush` commands fail if the database container is *running* but not yet
  *accepting connections*. A healthcheck plus condition fixes the race.
- **Secrets via `${VAR:?error}`** — fail fast when required variables are
  missing instead of starting with empty passwords.
- **Named volume for `sites/default/files`** — keeps user uploads out of the
  bind-mounted codebase.

---

## Common commands

```bash
docker compose up -d              # start stack in background
docker compose up -d --build      # rebuild images first
docker compose down               # stop and remove containers (volumes kept)
docker compose down -v            # ALSO delete named volumes (destroys DB!)
docker compose ps                 # container status + health
docker compose logs -f php        # follow logs of one service
docker compose exec php bash      # shell into running container
docker compose exec php vendor/bin/drush cr   # run drush inside the stack
docker compose run --rm php composer install  # one-off command container
docker compose config             # render the final merged config (debug)
docker compose watch              # sync+rebuild on file changes (dev loop)
```

---

## Dev vs prod configuration

Compose merges multiple files; later files override earlier ones.
`compose.override.yaml` is loaded automatically for local development:

```
compose.yaml            # base — shared definition
compose.override.yaml   # dev only — bind mounts, xdebug, exposed ports
compose.prod.yaml       # prod — restart policies, no source bind mount
```

```bash
docker compose up -d                                   # base + override (dev)
docker compose -f compose.yaml -f compose.prod.yaml up -d   # prod set
```

Use **profiles** for optional services (e.g. Solr or Mailpit only when
needed):

```yaml
services:
  solr:
    image: solr:9
    profiles: ["search"]
```

```bash
docker compose --profile search up -d
```

---

## Best practices

- Pin image tags (`mariadb:11.4`, not `latest`) so the stack is reproducible.
- One process per container; php-fpm and nginx are separate services.
- Put everything secret in `.env` (gitignored) and reference with `${VAR}`.
- Add a `healthcheck` to every service another service depends on.
- For Drupal, mount the project root once and let nginx mount it read-only.
- Run `docker compose config` after edits — it validates and shows the merge
  result before anything starts.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| Drupal install fails with "connection refused" to DB | Add DB `healthcheck` + `depends_on.condition: service_healthy` |
| Changes to compose.yaml have no effect | `docker compose up -d` again (recreates changed services); check `docker compose config` |
| Port already allocated | Another stack uses the host port — change `ports:` mapping or `docker compose down` the other project |
| Permission errors on `sites/default/files` | Align container user UID with host (`user:` key) or fix volume ownership in entrypoint |
| Stale vendor/ after switching branches | `docker compose run --rm php composer install` |
| `version` is obsolete warning | Delete the top-level `version:` key |
| Database empty after restart | You ran `down -v` — named volumes were deleted; restore from backup |

Versions

RepositoryScoreLicence
This page · siva01c/claude-plugins100MIT
znlgis/opengis-skills100MIT
magnus919/agent-skills100MIT
claude-dev-suite/claude-dev-suite100MIT
ajyadav013/claude-kit100MIT
BagelHole/DevOps-Security-Agent-Skills100MIT

Database snapshot: 13.11.2026 · package version 45c6ad5fec04 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100docker-compose-basics
    Use when defining and running multi-container Docker applications with Docker Compose YAML configuration.
  • 100docker-deploy
    Use when creating Dockerfiles, docker-compose configs, or containerizing applications. Covers multi-stage builds, image optimization, compose patterns for dev and production, health checks, signal handling, and security hardening.
  • 90docker-compose-helper
    Use when the user asks to create, debug, or modify Docker Compose files, compose.yaml, docker-compose.yml, service dependencies, healthchecks, ports, volumes, networks, environment variables, or local multi-container development stacks. Use this skill even if the user says…
  • 100generating-docker-compose-files
    Execute use when you need to work with Docker Compose. This skill provides Docker Compose file generation with comprehensive guidance and automation. Trigger with phrases like "generate docker-compose", "create compose file", or "configure multi-container app".
  • 100generating-docker-compose-files
    Execute use when you need to work with Docker Compose. This skill provides Docker Compose file generation with comprehensive guidance and automation. Trigger with phrases like "generate docker-compose", "create compose file", or "configure multi-container app".
  • 100docker-compose-setup
    Set up and orchestrate multi-container Docker applications using docker-compose, including service configuration, networking, volumes, and environment management. Use when the user requests docker compose setup or provides relevant inputs for this workflow.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.