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.
- Author
- siva01c ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 26.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.09.2026, without references to retired models or APIs.
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
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
- compose.yaml essentials
- Common commands
- Dev vs prod configuration
- Best practices
- Troubleshooting
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
| Repository | Score | Licence |
|---|---|---|
| This page · siva01c/claude-plugins | 100 | MIT |
| znlgis/opengis-skills | 100 | MIT |
| magnus919/agent-skills | 100 | MIT |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| ajyadav013/claude-kit | 100 | MIT |
| BagelHole/DevOps-Security-Agent-Skills | 100 | MIT |
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.