Docker Compose: полное руководство с примерами

Docker Compose — инструмент оркестрации контейнеров, который позволяет описывать и запускать многоконтейнерные приложения одним файлом. Вместо десятков команд docker run вы определяете сервисы в YAML, и Compose поднимает всю инфраструктуру одной командой. В этом руководстве разберём синтаксис, ключевые концепции и практические сценарии использования.

Что такое Docker Compose

Docker Compose — это инструмент командной строки, входящий в состав Docker Desktop. Он читает файл docker-compose.yml (или compose.yaml) и создаёт сети, volumes и контейнеры согласно описанной конфигурации. Compose особенно полезен для локальной разработки, когда нужно поднять базу данных, кэш, очередь сообщений и само приложение одновременно.

Основные преимущества:

• Декларативная конфигурация — вся инфраструктура описана в одном файле
• Изоляция проектов — каждый проект получает свою сеть и префикс контейнеров
• Воспроизводимость — одинаковое окружение на всех машинах разработчиков
• Простота — docker compose up -d вместо скриптов и документации

Для быстрой генерации конфигурации используйте Docker Compose Builder на reChecker.

Установка и версии

Compose V2 встроен в Docker Desktop. Для Linux установите плагин:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Проверка
docker compose version

Файлы совместимы с Compose V1 (docker-compose) и V2 (docker compose). Рекомендуется использовать V2 — он поддерживает Compose Specification и новые возможности.

Версии формата

Версия	Особенности
2.x	Поддержка сетей, расширенные опции
3.x	Упрощённый синтаксис, совместимость со Swarm
3.8+	Рекомендуемая для новых проектов

Структура docker-compose.yml

Базовый файл состоит из секций services, networks и volumes:

services:
  app:
    image: nginx:alpine
    ports:
      - "8080:80"

networks:
  default:
    driver: bridge

volumes:
  data:

Секция services обязательна. Каждый сервис — это контейнер с именем, образом и настройками. Сети и volumes опциональны, но часто необходимы для связи между контейнерами и сохранения данных.

Сервисы: ключевые директивы

image и build

services:
  # Готовый образ из реестра
  db:
    image: postgres:16-alpine

  # Сборка из Dockerfile
  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: myapp:latest

При использовании build образ создаётся при первом запуске. Директива image задаёт имя и тег результата сборки.

ports и expose

ports:
  - "3000:3000"      # host:container
  - "127.0.0.1:8080:80"  # только localhost
  - "9000"           # случайный порт на хосте

expose:
  - "5432"           # порт доступен только в сети Compose

ports публикует порты на хост. expose делает порт видимым только для других сервисов в той же сети.

environment и env_file

environment:
  NODE_ENV: production
  DATABASE_URL: postgres://user:pass@db:5432/mydb
  - DEBUG=1           # альтернативный синтаксис

env_file:
  - .env
  - .env.production

Переменные из env_file переопределяются значениями из environment. Файл .env в корне проекта подхватывается автоматически для подстановки в значения.

volumes

volumes:
  - /host/path:/container/path     # bind mount
  - named_volume:/container/path   # named volume
  - ./config:/app/config:ro        # read-only

Named volumes управляются Docker и сохраняют данные между перезапусками. Bind mounts привязывают директорию хоста — удобно для разработки с hot-reload.

depends_on

services:
  app:
    depends_on:
      - db
      - redis

  db:
    image: postgres:16

  redis:
    image: redis:alpine

Compose запускает контейнеры в порядке зависимостей. Важно: depends_on не ждёт готовности сервиса — PostgreSQL может ещё инициализироваться. Для ожидания готовности используйте condition: service_healthy с healthcheck.

healthcheck

db:
  image: postgres:16
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    timeout: 3s
    retries: 5
    start_period: 10s

app:
  depends_on:
    db:
      condition: service_healthy

С condition: service_healthy приложение не стартует, пока база не пройдёт проверку. Подробнее о стеках с базами — в статье Docker Compose для веб-разработки.

Сети

По умолчанию Compose создаёт сеть projectname_default. Все сервисы получают DNS-имена по имени сервиса: db, redis, app. Обращение к db:5432 из контейнера app работает автоматически.

Кастомные сети:

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true   # без доступа в интернет

services:
  web:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

Сеть internal: true изолирует контейнеры от внешнего мира — полезно для баз данных.

Volumes

Named volumes объявляются в корне и подключаются к сервисам:

volumes:
  postgres_data:
  redis_data:

services:
  db:
    volumes:
      - postgres_data:/var/lib/postgresql/data
  redis:
    volumes:
      - redis_data:/data

Данные сохраняются при docker compose down. Для полного удаления используйте docker compose down -v.

Профили

Профили позволяют запускать подмножество сервисов:

services:
  app:
    image: myapp
    profiles:
      - production

  dev-tools:
    image: dev-container
    profiles:
      - dev

  db:
    image: postgres

docker compose up -d              # только db (без профиля)
docker compose --profile dev up   # db + dev-tools
docker compose --profile production up  # db + app

Переменные и подстановка

Compose поддерживает переменные окружения в значениях:

services:
  app:
    image: myapp:${TAG:-latest}
    environment:
      DB_HOST: ${DB_HOST:-db}

Синтаксис ${VAR:-default} подставляет значение или default при отсутствии. Файл .env в корне проекта загружается автоматически.

Полезные команды

Команда	Описание
docker compose up -d	Запуск в фоне
docker compose down	Остановка и удаление контейнеров
docker compose ps	Список контейнеров
docker compose logs -f app	Логи сервиса
docker compose exec app sh	Shell в контейнере
docker compose build --no-cache	Пересборка без кэша
docker compose config	Валидация и вывод итоговой конфигурации

Рекомендации для продакшена

1. Не храните секреты в YAML — используйте Docker secrets или внешние системы (Vault, AWS Secrets Manager)
2. Ограничивайте ресурсы — deploy.resources.limits для CPU и памяти
3. Используйте healthcheck — для корректного depends_on и мониторинга
4. Версионируйте образы — не используйте latest в продакшене
5. Разделяйте конфигурации — docker-compose.yml для базы, docker-compose.override.yml для локальных переопределений

Ограничение ресурсов

services:
  app:
    image: myapp:1.0
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          memory: 256M

В режиме docker compose up (без Swarm) директива deploy может не применяться. Используйте mem_limit и cpus на уровне сервиса для совместимости.

Множественные файлы

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Второй файл переопределяет и дополняет первый. Удобно для разных окружений без дублирования.

Расширенные сценарии

Restart policies

services:
  app:
    image: myapp
    restart: unless-stopped

Варианты: no, always, on-failure, unless-stopped. Для продакшена обычно unless-stopped или on-failure.

Логирование

services:
  app:
    image: myapp
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Ограничивает размер логов на диске. Альтернативы: syslog, journald, awslogs.

Расширение конфигурации

Файл docker-compose.override.yml автоматически подхватывается при docker compose up. Используйте его для локальных переопределений (порты, volumes с исходниками), не коммитьте чувствительные данные.

Отладка и диагностика

# Детальный вывод конфигурации
docker compose config

# Запуск с выводом логов
docker compose up

# Проверка зависимостей
docker compose config --services

При проблемах с сетью проверьте docker network ls и docker network inspect. Убедитесь, что сервисы в одной сети.

Миграция с docker-compose на docker compose

Compose V1 (docker-compose) — отдельный бинарник. V2 (docker compose) — плагин Docker CLI. Команды совместимы, синтаксис файлов одинаков. Для миграции достаточно установить плагин и заменить дефис на пробел в командах.

Сравнение с альтернативами

Инструмент	Масштаб	Сложность	Применение
Docker Compose	1 хост	Низкая	Разработка, малые деплои
Docker Swarm	Кластер	Средняя	Оркестрация без K8s
Kubernetes	Кластер	Высокая	Продакшен, масштабирование

Compose не предназначен для высокодоступных кластеров. Для одного сервера или локальной разработки его возможностей достаточно.

Docker Compose покрывает большинство сценариев локальной разработки и небольших деплоев. Для масштабируемых кластеров рассмотрите Kubernetes или Docker Swarm. Начните с Docker Compose Builder на reChecker — он поможет сгенерировать базовую конфигурацию под ваш стек. Готовые стеки для WordPress, Node.js и PHP — в Docker Compose для веб-разработки.