Docker Compose - это инструмент, который запускает несколько связанных контейнеров одной командой по описанию в YAML-файле. Вместо пяти длинных docker run с портами, томами и переменными вы один раз пишете compose.yaml, а потом поднимаете всё приложение через docker compose up -d и останавливаете через docker compose down. Ниже - как устроен файл, рабочий пример с сайтом и базой данных, основные команды и ошибки, на которых чаще всего спотыкаются.

Зачем нужен Docker Compose

Реальное приложение редко живёт в одном контейнере. Сайту нужна база данных, кэш, иногда очередь задач и панель администратора. Запускать их по отдельности неудобно: надо помнить параметры каждого контейнера, создавать сеть, следить за порядком запуска.

Compose решает это так:

  • все сервисы, их порты, тома и переменные описаны в одном файле, который лежит в репозитории рядом с кодом;
  • для проекта автоматически создаётся отдельная сеть, и контейнеры находят друг друга по имени сервиса;
  • окружение одинаково поднимается у всех разработчиков и на тестовом сервере;
  • одна команда пересоздаёт только те контейнеры, конфигурация которых изменилась.

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

docker compose или docker-compose

Существуют две версии инструмента:

Compose V1 Compose V2
Команда docker-compose (через дефис) docker compose (через пробел)
Написан на Python, ставился отдельно Go, плагин Docker CLI
Статус больше не поддерживается актуальная версия
Установка отдельный пакет или pip входит в Docker Desktop, на Linux пакет docker-compose-plugin

Синтаксис файлов у них почти одинаковый, поэтому старые инструкции с docker-compose up работают, если заменить дефис на пробел. Проверить, что V2 установлен:

bash
docker compose version

Если команда не найдена, на Ubuntu и Debian с официальным репозиторием Docker поставьте плагин:

bash
sudo apt install docker-compose-plugin

Из чего состоит compose.yaml

Файл по умолчанию называется compose.yaml. Старые имена docker-compose.yml и docker-compose.yaml тоже читаются. Ключ version: в начале файла больше не нужен: современный Compose его игнорирует и выводит предупреждение.

Верхний уровень файла:

Раздел Что описывает
services контейнеры приложения: из какого образа, какие порты, тома и переменные
volumes именованные тома для данных, которые переживают пересоздание контейнеров
networks дополнительные сети, если одной сети по умолчанию мало
configs, secrets конфигурационные файлы и секреты, которые монтируются в контейнеры

Структура compose.yaml: сервисы, сеть проекта и тома

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

  • image - готовый образ из Docker Hub или своего реестра;
  • build - путь к папке с Dockerfile, если образ собирается из исходников;
  • ports - проброс портов в формате "порт_хоста:порт_контейнера";
  • volumes - тома и папки хоста, подключённые внутрь контейнера;
  • environment и env_file - переменные окружения;
  • depends_on - от каких сервисов зависит этот;
  • restart - политика перезапуска: no, always, on-failure, unless-stopped;
  • healthcheck - команда, по которой Docker понимает, что сервис готов к работе.

Пример: WordPress и MariaDB

Классический случай - сайт плюс база данных. Создайте папку проекта и в ней два файла.

.env с паролями (этот файл не коммитят в Git, добавьте его в .gitignore):

text
DB_PASSWORD=сложный_пароль
DB_ROOT_PASSWORD=другой_сложный_пароль

compose.yaml:

yaml
services:
  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wp
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5

  wordpress:
    image: wordpress:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wp
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DB_NAME: wordpress
    volumes:
      - wp_data:/var/www/html

volumes:
  db_data:
  wp_data:

Запуск:

bash
docker compose up -d

Через минуту сайт откроется на http://localhost:8080. Обратите внимание на три детали:

  1. WordPress подключается к базе по адресу db - это имя сервиса. Compose сам создал общую сеть и DNS-имена, IP-адреса знать не нужно.
  2. Порт базы наружу не проброшен: к MariaDB может обратиться только WordPress изнутри сети проекта.
  3. Данные лежат в именованных томах db_data и wp_data, поэтому docker compose down не удалит ни базу, ни загруженные картинки.

depends_on и healthcheck: порядок запуска

Простой depends_on: [db] гарантирует только, что контейнер базы будет запущен раньше. Но запущен не значит готов: MariaDB ещё несколько секунд инициализирует файлы, и приложение в это время получает отказ в подключении.

Чтобы сервис ждал реальной готовности, у зависимости должен быть healthcheck, а в depends_on - условие condition: service_healthy, как в примере выше.

Как depends_on с condition: service_healthy ждёт готовности базы

Условие Когда стартует зависимый сервис
service_started (по умолчанию) сразу после запуска контейнера зависимости
service_healthy когда healthcheck зависимости вернул успех
service_completed_successfully когда зависимость завершилась с кодом 0, удобно для миграций

Сборка своего образа

Если приложение ваше, вместо image укажите build. Пример для сервиса на Node.js, который собирается из Dockerfile в текущей папке и при разработке видит изменения кода:

yaml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    env_file: .env
    volumes:
      - ./src:/app/src
    depends_on:
      - redis

  redis:
    image: redis:7-alpine

После правки Dockerfile или зависимостей образ нужно пересобрать:

bash
docker compose up -d --build

Основные команды Docker Compose

Все команды выполняются в папке, где лежит compose.yaml, или с ключом -f путь/к/файлу.

Команда Что делает
docker compose up -d создаёт и запускает все сервисы в фоне
docker compose up -d --build то же, но сначала пересобирает образы с build
docker compose down останавливает и удаляет контейнеры и сеть, тома остаются
docker compose down -v то же плюс удаляет именованные тома - данные пропадут
docker compose ps список контейнеров проекта и их состояние
docker compose logs -f wordpress логи сервиса в реальном времени
docker compose exec db bash открыть оболочку в работающем контейнере
docker compose run --rm app npm test разовый запуск команды в новом контейнере
docker compose stop / start остановить и запустить без удаления контейнеров
docker compose restart app перезапустить сервис
docker compose pull скачать свежие версии образов
docker compose config показать итоговую конфигурацию с подставленными переменными

Шпаргалка по командам docker compose

Обновить сервисы до новых версий образов без остановки остальных:

bash
docker compose pull
docker compose up -d

Compose пересоздаст только те контейнеры, у которых изменился образ или настройки.

Переменные окружения и несколько файлов

Compose автоматически читает файл .env из папки проекта и подставляет значения в конструкции ${ИМЯ}. Можно задать значение по умолчанию: ${PORT:-8080}. Файл, указанный в env_file, наоборот, передаёт переменные внутрь контейнера, а не в сам compose.yaml. Эти два механизма часто путают.

Для разных окружений удобно держать базовый файл и файл с отличиями. Если рядом с compose.yaml лежит compose.override.yaml, Compose объединит их автоматически. Для продакшена файлы указывают явно:

bash
docker compose -f compose.yaml -f compose.prod.yaml up -d

Посмотреть, что получилось после слияния, помогает docker compose config.

Частые ошибки

Ошибка Причина Решение
docker: 'compose' is not a docker command не установлен плагин Compose V2 установить docker-compose-plugin или Docker Desktop
port is already allocated порт хоста занят другим процессом или контейнером поменять левую часть в ports, например "8081:80"
Приложение не видит базу по localhost внутри контейнера localhost - это сам контейнер обращаться по имени сервиса: db, redis
База пустая после перезапуска данные лежали внутри контейнера без тома или выполнен down -v подключить именованный том и не использовать -v без нужды
the attribute version is obsolete в файле остался ключ version: удалить строку, на работу это не влияет
Изменения в Dockerfile не применились Compose взял старый образ из кэша запустить docker compose up -d --build
Ошибка отступов YAML табуляция или разный отступ использовать только пробелы, проверить через docker compose config

Файл compose.yaml стоит хранить в репозитории вместе с кодом проекта, а .env с паролями - нет. Как удобно вести такой репозиторий, разобрано в шпаргалке по командам Git.