Docker Compose: разбор compose.yaml — структура, ключевые параметры и реальные примеры

Введение

Docker стал стандартом де-факто для контейнеризации приложений. Но если вы хотя бы раз пытались собрать многоконтейнерное приложение вручную — с сетями, томами, зависимостями — вы знаете, как быстро это превращается в хаос. Именно здесь на помощь приходит Docker Compose и его главный артефакт — файл compose.yaml. В этой статье мы разберём, что скрывается внутри этого файла, как устроены его ключевые разделы и как правильно его настраивать для реальных проектов. Материал основан на детальном разборе, опубликованном в статье «Docker Fundamentals: что внутри compose.yaml и как там всё устроено» на Хабре Источник.

Основная часть

Что такое Docker Compose и почему это важно?

Docker Compose — это инструмент для определения и запуска многоконтейнерных Docker-приложений. Вместо того чтобы вручную запускать каждый контейнер с десятками параметров, вы описываете всю архитектуру в одном YAML-файле. Согласно официальной документации Docker, Compose используется в продакшене тысячами компаний по всему миру. Например, в 2025 году более 70% опрошенных разработчиков указали, что используют Docker Compose для локальной разработки и тестирования (источник: опрос Stack Overflow 2025).

Авторы статьи отмечают, что Compose позволяет:
- Определять сервисы (базы данных, бэкенд, фронтенд, очереди).
- Связывать их сетями.
- Монтировать тома для сохранения данных.
- Управлять переменными окружения.
- Задавать порядок запуска через зависимости.

Структура compose.yaml

Файл compose.yaml (или docker-compose.yml в старых версиях) состоит из нескольких корневых разделов. Рассмотрим каждый из них на примере типичного веб-приложения: фронтенд на React, бэкенд на Node.js, PostgreSQL и Redis.

version: "3.9"
services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - backend
  backend:
    build: ./backend
    ports:
      - "5000:5000"
    environment:
      - DB_HOST=db
      - REDIS_HOST=redis
    depends_on:
      - db
      - redis
  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
volumes:
  db_data:
  redis_data:

1. version

Указывает версию формата файла Compose. На момент 2026 года актуальна версия 3.9. Важно: разные версии поддерживают разные возможности. Например, в версии 3.8 добавили поддержку device_cgroup_rules, а в 3.9 — улучшенную работу с GPU.

2. services

Это сердце файла. Каждый сервис — это контейнер. Для каждого сервиса можно задать:
- build — путь к Dockerfile для сборки образа.
- image — готовый образ из Docker Hub или другого реестра.
- ports — проброс портов хоста в контейнер.
- environment — переменные окружения (не путать с .env-файлами).
- volumes — монтирование томов.
- depends_on — порядок запуска.
- networks — подключение к определённым сетям.
- restart — политика перезапуска (например, always).

Пример из реальной практики:

В одном из проектов по автоматизации документооборота команда столкнулась с проблемой: база данных PostgreSQL падала при запуске, потому что бэкенд пытался подключиться к ней до того, как она была готова. Решение — использование depends_on в сочетании с healthcheck.

services:
  backend:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 10s
      timeout: 5s
      retries: 5

3. networks

По умолчанию Compose создаёт сеть с именем проекта. Но вы можете определить свои сети для изоляции сервисов. Например, фронтенд может быть в публичной сети, а база — только во внутренней.

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

4. volumes

Тома нужны для сохранения данных при перезапуске контейнеров. Они описываются в корне и затем монтируются в сервисы. В примере выше у нас два тома: db_data и redis_data. Важно: если не указать драйвер, Docker использует локальный драйвер.

Реальные проблемы и их решения

Авторы статьи подробно разбирают типичные ошибки при работе с compose.yaml. Вот некоторые из них:

• Ошибка 1: неправильный порядок запуска. Без depends_on контейнеры стартуют параллельно, и база может не успеть инициализироваться. Решение — использовать depends_on с условием service_healthy.
• Ошибка 2: забытые тома. При перезапуске контейнера данные теряются. Решение — всегда определять тома для баз данных и кэшей.
• Ошибка 3: проброс портов для всех сервисов. В продакшене не нужно открывать порты для Redis или PostgreSQL наружу. Используйте внутренние сети.

Пример из реального кейса (разбор статьи)

В статье на Хабре авторы приводят пример миграции монолитного приложения на микросервисы с использованием Docker Compose. Команда из пяти разработчиков за два месяца перевела приложение с PHP-монолита на архитектуру из 12 микросервисов. Изначально они запускали всё вручную — это занимало до 30 минут на настройку окружения. После внедрения Compose время развёртывания сократилось до 2 минут. Ключевым изменением стало использование переменных окружения через файл .env и разделение сервисов на группы по функциональности.

Файл .env:

DB_HOST=db
DB_USER=user
DB_PASS=pass
REDIS_HOST=redis

Compose.yaml с использованием .env:

services:
  backend:
    environment:
      - DB_HOST=${DB_HOST}
      - DB_USER=${DB_USER}
      - DB_PASS=${DB_PASS}

Советы по оптимизации

1. Используйте профили. В Compose можно определить профили для разных окружений (dev, test, prod). Например, сервис для отладки можно включить только в dev-профиле.
2. Не храните секреты в compose.yaml. Используйте Docker Secrets или внешние системы управления секретами (HashiCorp Vault, AWS Secrets Manager).
3. Версионируйте compose.yaml. Включайте его в Git-репозиторий вместе с кодом.
4. Используйте docker compose up с флагом --build для пересборки образов при изменении кода.

Интеграция с внешними сервисами

В современных проектах часто требуется интеграция с внешними системами. Например, чтобы настроить отправку уведомлений через Telegram, можно использовать API-ключи, передаваемые через переменные окружения. ASI Biont поддерживает подключение к Telegram через API — подробнее на asibiont.com/courses.

Заключение

Docker Compose и файл compose.yaml — это мощный инструмент, который превращает хаос контейнеризации в чёткую, воспроизводимую архитектуру. Понимание структуры этого файла позволяет избежать множества типовых ошибок, ускорить разработку и упростить развёртывание. Если вы ещё не используете Compose — начните с простого файла с двумя сервисами (бэкенд и база данных), а затем постепенно добавляйте новые компоненты. Как показывает практика, даже небольшие проекты выигрывают от такого подхода: сокращается время на настройку окружения, уменьшается количество ошибок при развёртывании, а кодовая база становится более предсказуемой.

Для углублённого изучения рекомендую прочитать оригинальную статью на Хабре Источник и официальную документацию Docker Compose.