re:re:actable
Урок 024 минуты чтения

Как устроен 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Документация внутренних портов
volumesNamed volumes, bind mounts, анонимные volumes
networksСети сервиса (по умолчанию — default)
depends_onПорядок запуска и условия готовности
healthcheckПроверка здоровья
restartno, 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.0

docker 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам