Как устроен compose.yaml и какие поля сервисов нужно знать
На этой странице
compose.yaml состоит из разделов верхнего уровня: services (обязательный), volumes, networks, secrets, configs и name. В сервисе главное — откуда взять образ (image или build), как его запустить (command, entrypoint, environment, env_file), как связать с миром (ports, networks, volumes), когда запускать (depends_on, healthcheck, restart, profiles). Итоговую конфигурацию после подстановок показывает docker compose config.
Вопрос
Как устроен compose.yaml и какие поля сервиса нужно знать?
Структура файла
name: shop # имя проекта (иначе — имя каталога)
services: # контейнеры приложения
api: { ... }
db: { ... }
volumes: # named volumes
pgdata:
networks: # пользовательские сети (default создаётся сам)
internal:
secrets: # секреты, монтируемые файлами
db_password:
file: ./secrets/db_password.txtПолный пример сервиса
services:
api:
build:
context: ./api
dockerfile: Dockerfile
target: runner
args:
NODE_VERSION: "24"
image: ghcr.io/team/api:${TAG:-dev} # имя для собранного образа
command: ["node", "dist/main.js"]
environment:
NODE_ENV: production
DATABASE_URL: postgres://app:secret@db:5432/app
env_file:
- .env
ports:
- "3000:3000"
volumes:
- uploads:/app/uploads
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
interval: 10s
retries: 5
restart: unless-stopped
mem_limit: 512m
init: trueСправочник полей
| Поле | Зачем |
|---|---|
image | Готовый образ; вместе с build — имя собранного образа |
build | Сборка: context, dockerfile, target, args |
command | Заменяет CMD образа |
entrypoint | Заменяет ENTRYPOINT образа |
environment | Переменные окружения контейнера |
env_file | Переменные из файла |
ports | Публикация на хост HOST:CONTAINER |
expose | Документация внутренних портов |
volumes | Named volumes, bind mounts, анонимные volumes |
networks | Сети сервиса (по умолчанию — default) |
depends_on | Порядок запуска и условия готовности |
healthcheck | Проверка здоровья |
restart | no, on-failure, always, unless-stopped |
profiles | Сервис запускается только с указанным профилем |
working_dir, user | Рабочий каталог и пользователь |
init | Лёгкий init как PID 1 для корректной обработки сигналов |
mem_limit, cpus | Лимиты ресурсов |
extra_hosts | Записи в /etc/hosts, например host.docker.internal:host-gateway |
develop.watch | Синхронизация файлов для compose watch |
image и build вместе
api:
build: ./api
image: ghcr.io/team/api:1.4.0docker compose build соберёт образ и назовёт его указанным именем, docker compose push отправит его в registry. Без image Compose сам назовёт образ <проект>-api.
Подстановка переменных
image: ghcr.io/team/api:${TAG:-latest} # значение по умолчанию
environment:
API_KEY: ${API_KEY:?API_KEY is required} # ошибка, если не заданаЗначения берутся из окружения shell и файла .env рядом с compose.yaml. Это подстановка в YAML, а не передача в контейнер — подробнее в уроке про переменные окружения.
Повторное использование: YAML-якоря и extends
x-node-defaults: &node-defaults
restart: unless-stopped
init: true
env_file: [.env]
services:
api:
<<: *node-defaults
build: ./api
worker:
<<: *node-defaults
build: ./api
command: ["node", "dist/worker.js"]Ключи с префиксом x- Compose игнорирует — в них удобно держать общие фрагменты.
Частые ошибки
- Ставить
container_nameвезде: ломается масштабирование (--scale) и параллельные проекты. - Ждать, что
depends_onбезconditionдождётся готовности БД. - Хранить production-секреты в
environmentпрямо в файле. - Не объявить named volume в разделе
volumesверхнего уровня. - Использовать поля
deploy.*и ждать, что все они работают вне Swarm (лимиты ресурсов работают,replicasиplacement— нет).
Что важно помнить
services— единственный обязательный раздел.- Compose объединяет значения из нескольких файлов и переменных — проверяй итог через
docker compose config. commandиentrypointпереопределяют Dockerfile так же, как аргументыdocker run.
Мини-шпаргалка
image/build— откуда образ.environment/env_file— переменные.ports,volumes,networks— связи.depends_on+healthcheck— порядок.restart,profiles,init— поведение.x-*+ якоря — общие настройки.
Документация
Docker: Compose file reference, Docker: Services top-level elements, Docker: Interpolation.