Паттерны Docker Compose
Делает compose.yaml с depends_on по проверкам здоровья, сайдкаром для distroless-образов, именованными томами, секретами вне файла и override с Compose Watch. Для случаев, когда в стек добавляют сервис или он стартует раньше своей зависимости.
docker-compose-patterns- Автор
- Docker
- Источник
- docker/skills/skills/docker-compose-patterns @ caeee20
- Лицензия
- Apache-2.0 · Copyright 2026 Docker, Inc.
Об этом скилле
Что делает
Скилл отвечает за compose.yaml и compose.override.yaml: связи сервисов, порядок запуска и хранение данных. Файл называется compose.yaml, а не устаревшим docker-compose.yml; сервис, который должен быть готов раньше зависимых, указывают в depends_on с condition: service_healthy, и у него есть healthcheck на его собственном клиенте (pg_isready, redis-cli ping). Постоянные данные лежат в именованных томах, bind mount — только для исходников в разработке. Секретов в файле нет: env_file, Docker secrets или подстановка вида ${DB_PASSWORD:-postgres}, а .env — в .gitignore. Всё, что нужно только для разработки, уходит в override, синхронизация файлов — в develop.watch.
В distroless- и scratch-образах нет ни shell, ни curl, поэтому проверку здоровья выносят в сайдкар с network_mode: "service:api", и зависимые сервисы ждут именно его. А docker compose down -v, docker compose rm -v и удаление томов проекта Compose агент запускает только после явного согласия пользователя, сначала назвав, какие данные пропадут.
В папке есть справочники по порядку запуска — с проверками для шести популярных сервисов — и по томам и сетям. В assets/ — стек «приложение + Postgres + Redis», override для разработки и семь типичных ошибок в формате «было — стало». Скрипт scripts/verify-compose.sh запускает docker compose config --quiet, чтобы подставленные пароли не попали в логи. Есть и инструкция по проверке, и тестовые промпты.
Когда включать и когда не надо
Чтобы добавить в стек базу или кеш, написать override для разработки или понять, почему сервис стартует раньше, чем готова его зависимость. Нужен Compose v2.
Не нужен для первого набора Docker-файлов в проекте и для внутренностей Dockerfile: кеша, размера образа, пользователя в рантайме.
Как поставить и вызвать
Команда установки ниже скачивает всю папку. Агент сам подхватывает скилл по описанию. Вызвать вручную:
- Claude Code:
/docker-compose-patternsили попросить скилл по имени. - Codex:
$docker-compose-patterns. - Cursor: наберите
/в чате Agent и выберитеdocker-compose-patterns.
Пример: /docker-compose-patterns Добавь Postgres и Redis так, чтобы API стартовал, только когда оба здоровы, а bind mount для разработки вынеси в override.
Чем отличается от похожих
Других скиллов, которые так подробно разбирают Compose, в каталоге нет. Перевод проекта в Docker создаёт только стартовый compose.yaml. Защита от опасных команд Docker берёт на себя docker system prune и тома вне Compose, а удаление внутри Compose возвращает сюда. Аудит секретов и конфигурации ищет захардкоженные секреты по всему репозиторию и его истории в git; этот скилл лишь не пускает их в compose.yaml. Ревью манифестов Kubernetes задаёт похожие вопросы — закреплённые теги образов, проверки здоровья, секреты вне файла — для сервисов, которые работают в кластере, а не под Compose.
Установка
Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.
Скилл написан на английском — агент поймёт его и ответит вам по-русски.
curl -fsSL --create-dirs -o ~/.claude/skills/docker-compose-patterns/SKILL.md https://anymodel.org/en/skills/docker/docker-compose-patterns/SKILL.md -o ~/.claude/skills/docker-compose-patterns/LICENSE https://anymodel.org/en/skills/docker/docker-compose-patterns/LICENSE -o ~/.claude/skills/docker-compose-patterns/agents/openai.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/agents/openai.yaml -o ~/.claude/skills/docker-compose-patterns/assets/bad-vs-good.md https://anymodel.org/en/skills/docker/docker-compose-patterns/assets/bad-vs-good.md -o ~/.claude/skills/docker-compose-patterns/assets/compose-dev-override.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/assets/compose-dev-override.yaml -o ~/.claude/skills/docker-compose-patterns/assets/compose-web-app.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/assets/compose-web-app.yaml -o ~/.claude/skills/docker-compose-patterns/checks/verification.md https://anymodel.org/en/skills/docker/docker-compose-patterns/checks/verification.md -o ~/.claude/skills/docker-compose-patterns/evals/docker-compose-patterns.md https://anymodel.org/en/skills/docker/docker-compose-patterns/evals/docker-compose-patterns.md -o ~/.claude/skills/docker-compose-patterns/references/service-dependencies.md https://anymodel.org/en/skills/docker/docker-compose-patterns/references/service-dependencies.md -o ~/.claude/skills/docker-compose-patterns/references/volumes-and-networks.md https://anymodel.org/en/skills/docker/docker-compose-patterns/references/volumes-and-networks.md -o ~/.claude/skills/docker-compose-patterns/scripts/verify-compose.sh https://anymodel.org/en/skills/docker/docker-compose-patterns/scripts/verify-compose.sh -o ~/.claude/skills/docker-compose-patterns/skill.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/skill.yaml && chmod +x ~/.claude/skills/docker-compose-patterns/scripts/verify-compose.sh
curl -fsSL --create-dirs -o ~/.agents/skills/docker-compose-patterns/SKILL.md https://anymodel.org/en/skills/docker/docker-compose-patterns/SKILL.md -o ~/.agents/skills/docker-compose-patterns/LICENSE https://anymodel.org/en/skills/docker/docker-compose-patterns/LICENSE -o ~/.agents/skills/docker-compose-patterns/agents/openai.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/agents/openai.yaml -o ~/.agents/skills/docker-compose-patterns/assets/bad-vs-good.md https://anymodel.org/en/skills/docker/docker-compose-patterns/assets/bad-vs-good.md -o ~/.agents/skills/docker-compose-patterns/assets/compose-dev-override.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/assets/compose-dev-override.yaml -o ~/.agents/skills/docker-compose-patterns/assets/compose-web-app.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/assets/compose-web-app.yaml -o ~/.agents/skills/docker-compose-patterns/checks/verification.md https://anymodel.org/en/skills/docker/docker-compose-patterns/checks/verification.md -o ~/.agents/skills/docker-compose-patterns/evals/docker-compose-patterns.md https://anymodel.org/en/skills/docker/docker-compose-patterns/evals/docker-compose-patterns.md -o ~/.agents/skills/docker-compose-patterns/references/service-dependencies.md https://anymodel.org/en/skills/docker/docker-compose-patterns/references/service-dependencies.md -o ~/.agents/skills/docker-compose-patterns/references/volumes-and-networks.md https://anymodel.org/en/skills/docker/docker-compose-patterns/references/volumes-and-networks.md -o ~/.agents/skills/docker-compose-patterns/scripts/verify-compose.sh https://anymodel.org/en/skills/docker/docker-compose-patterns/scripts/verify-compose.sh -o ~/.agents/skills/docker-compose-patterns/skill.yaml https://anymodel.org/en/skills/docker/docker-compose-patterns/skill.yaml && chmod +x ~/.agents/skills/docker-compose-patterns/scripts/verify-compose.sh
foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','assets/bad-vs-good.md','assets/compose-dev-override.yaml','assets/compose-web-app.yaml','checks/verification.md','evals/docker-compose-patterns.md','references/service-dependencies.md','references/volumes-and-networks.md','scripts/verify-compose.sh','skill.yaml') { $p = Join-Path "$HOME\.claude\skills\docker-compose-patterns" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/docker/docker-compose-patterns/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','LICENSE','agents/openai.yaml','assets/bad-vs-good.md','assets/compose-dev-override.yaml','assets/compose-web-app.yaml','checks/verification.md','evals/docker-compose-patterns.md','references/service-dependencies.md','references/volumes-and-networks.md','scripts/verify-compose.sh','skill.yaml') { $p = Join-Path "$HOME\.agents\skills\docker-compose-patterns" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/docker/docker-compose-patterns/$f" -UseBasicParsing -OutFile $p }Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/docker/docker-compose-patterns/SKILL.md
SKILL.md
Docker Compose Patterns
Overview
This skill provides rules for creating, reviewing, and debugging Docker Compose configurations. Use it when the main artifact is compose.yaml or compose.override.yaml and the task is about service wiring rather than image-build internals.
When to use this skill
Activate this skill when:
- Creating a new
compose.yamlfor a project - Adding or modifying services in an existing Compose file
- Setting up development overrides with
compose.override.yaml - Debugging service startup ordering or connectivity issues
Do not use this skill when
Do not use this skill when:
- The project has no Docker setup yet and the main need is an initial scaffold
- The main task is writing or optimizing a
Dockerfile - The main task is improving build caching, image size, or runtime user configuration
Core guidance
File naming
Use compose.yaml as the canonical filename. Do not use docker-compose.yml or docker-compose.yaml — those are legacy names.
Service definitions
- Give services clear, lowercase names that reflect their role:
web,db,cache,worker. - Always pin image tags to a specific version. Never use
latestor omit the tag. - Set
restart: unless-stoppedfor long-running infrastructure services and non-development deployments. - Add
container_nameonly when external tools need a predictable name. Otherwise, let Compose generate names.
Dependency modeling
- Use
depends_onwithcondition: service_healthyfor services that must be ready before dependents start. - Every service listed in
depends_onwith a health condition must have ahealthcheckdefined. - Do not rely on
depends_onwithout conditions — it only guarantees container start, not readiness.
Health checks
- Always add a
healthcheckto database services (Postgres, MySQL, Redis, MongoDB). - Use the service's native client tool for health checks when available (e.g.,
pg_isready,redis-cli ping,mysqladmin ping). - Set reasonable
interval,timeout,retries, andstart_periodvalues. Start with:interval: 5s,timeout: 3s,retries: 3,start_period: 10s.
Health checks for distroless or scratch images
Distroless, scratch-based, and hardened images contain no shell, curl, or wget. Do not bake tools into these images — that defeats their purpose. Instead, use a healthcheck sidecar that shares the application's network namespace:
services:
api:
build:
context: .
target: runtime # distroless / hardened image
ports:
- "8080:8080"
# No healthcheck here — the image has no tools to run one
api-health:
image: curlimages/curl:8.22.0
network_mode: "service:api" # shares api's localhost
entrypoint: ["sleep", "infinity"] # keep sidecar alive for healthcheck
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 45s
deploy:
resources:
limits:
memory: 32M
Key points:
- The sidecar must stay alive with
entrypoint: ["sleep", "infinity"]so Compose can execute the healthcheck inside it. network_mode: "service:api"makeslocalhostinside the sidecar resolve to the api container's loopback — no extra networking needed.- Keep the sidecar lightweight with a resource limit (32MB is sufficient for curl).
- Services that depend on
apibeing ready should reference the sidecar, not the api directly:
worker:
depends_on:
api-health:
condition: service_healthy
Volumes
- Use named volumes for data that must persist across container recreations (database data, uploaded files).
- Use bind mounts only for development-time source code syncing.
- Define all named volumes in the top-level
volumes:key. - Do not mount the Docker socket unless the service genuinely requires it.
Networks
- For single-application stacks, the default network is sufficient. Do not create custom networks unless you need isolation between service groups.
- When creating custom networks, prefer bridge driver and give networks descriptive names.
- Use the top-level
networks:key to define all custom networks.
Environment variables
- Use
environment:for non-sensitive values that are few in number. - Use
env_file:pointing to a.envfile for longer lists of variables. - Never hardcode secrets (passwords, API keys) directly in
compose.yaml. Useenv_file:or Docker secrets. - When defaults are needed in the
environment:block for local development, use variable substitution with fallbacks:${DB_PASSWORD:-postgres}. Never write bare plaintext values for password fields. - Add
.envto.gitignore.
Development overrides
- Use
compose.override.yamlfor development-only settings. Compose loads it automatically alongsidecompose.yaml. - Put bind mounts for source code, debug ports, and development environment variables in the override file.
- Use
develop.watchfor file-syncing and auto-rebuild in development when supported. - Keep production-oriented settings in the base
compose.yamland override only what changes for development.
Compose Watch
- Prefer
develop.watchover manual bind mounts for development workflows. - Use
action: syncfor files that should be copied into the container on change (source code). - Use
action: rebuildfor files that require a full image rebuild (dependency files likepackage.json,requirements.txt). - Use
action: sync+restartfor configuration files that need a process restart.
Destructive commands
Some Compose commands delete data irreversibly. Before running any of the following, state exactly which data will be deleted and get explicit confirmation from the user — do not run them as a side effect of debugging, restarting, or "cleaning up" a stack:
docker compose down -v/docker compose down --volumes— deletes named volumes, including database data.docker volume rm/docker volume prunerun against a Compose project's volumes — deletes volumes directly. For the standalone case (no Compose project in play), seedocker-destructive-guardrailsinstead. A volume referenced viaexternal: trueisn't managed by the Compose project either (down -vwon't touch it) — treat it as the standalone case too: rundocker volume rmwithout-ffirst, and get explicit confirmation before deleting it.docker compose rm -v— deletes anonymous volumes attached to removed containers.
If the goal is only to restart services or reclaim containers/networks, use docker compose down (no -v) or docker compose restart instead — these leave named volumes intact.
Related skills
- For first-time Docker project scaffolding and baseline file creation, use
docker-project-foundations. - For Dockerfile internals, build caching, multi-stage builds, and
.dockerignore, usedocker-build-strategies. - For destructive Docker CLI commands outside Compose (
docker system prune,docker rm -f, image/network/builder pruning, standalone volume deletion) and a cross-product index of destructive-command guardrails, usedocker-destructive-guardrails.
References
references/service-dependencies.md— Detailed guidance ondepends_on, health check patterns for common databases, and startup ordering strategies.references/volumes-and-networks.md— Patterns for volume mounts, named volumes, bind mounts, and network configuration.
Assets
assets/compose-web-app.yaml— Complete multi-service web app (app + Postgres + Redis) with health checks, dependencies, and named volumes.assets/compose-dev-override.yaml— Development override showing bind mounts, debug ports, and Compose Watch configuration.assets/bad-vs-good.md— Before/after comparisons of common Compose mistakes and their fixes.
Scripts
scripts/verify-compose.sh— Validates the Compose project in the current directory withdocker compose config --quiet, without printing resolved configuration. Run it from the project root (the directory that containscompose.yaml), with the script path resolved under this skill's directory:
Replacebash "<skill-dir>/scripts/verify-compose.sh" [--help]<skill-dir>with the absolute path of the folder that contains thisSKILL.md; thescripts/path is relative to that folder, not to the project. Do not change into the skill directory first: the script validates whatever Compose project is in the current directory. If the skill directory cannot be resolved, rundocker compose config --quietdirectly. Exit status is0when the Compose configuration is valid or help is requested, the non-zero status fromdocker compose config --quietwhen validation fails, and2for invalid arguments. Plaindocker compose configcan expose interpolated andenv_filecredentials in tool output or logs; use quiet validation by default. Compose warnings and errors are still emitted and may contain sensitive details.
Checks
checks/verification.md— Detailed verification runbook for manual review.
Подключить через AnyModel API
Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.
AnyModel