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 установлен:
docker compose version
Если команда не найдена, на Ubuntu и Debian с официальным репозиторием Docker поставьте плагин:
sudo apt install docker-compose-plugin
Из чего состоит compose.yaml
Файл по умолчанию называется compose.yaml. Старые имена docker-compose.yml и docker-compose.yaml тоже читаются. Ключ version: в начале файла больше не нужен: современный Compose его игнорирует и выводит предупреждение.
Верхний уровень файла:
| Раздел | Что описывает |
|---|---|
services |
контейнеры приложения: из какого образа, какие порты, тома и переменные |
volumes |
именованные тома для данных, которые переживают пересоздание контейнеров |
networks |
дополнительные сети, если одной сети по умолчанию мало |
configs, secrets |
конфигурационные файлы и секреты, которые монтируются в контейнеры |

Основные параметры сервиса:
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):
DB_PASSWORD=сложный_пароль
DB_ROOT_PASSWORD=другой_сложный_пароль
compose.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:
Запуск:
docker compose up -d
Через минуту сайт откроется на http://localhost:8080. Обратите внимание на три детали:
- WordPress подключается к базе по адресу
db- это имя сервиса. Compose сам создал общую сеть и DNS-имена, IP-адреса знать не нужно. - Порт базы наружу не проброшен: к MariaDB может обратиться только WordPress изнутри сети проекта.
- Данные лежат в именованных томах
db_dataиwp_data, поэтомуdocker compose downне удалит ни базу, ни загруженные картинки.
depends_on и healthcheck: порядок запуска
Простой depends_on: [db] гарантирует только, что контейнер базы будет запущен раньше. Но запущен не значит готов: MariaDB ещё несколько секунд инициализирует файлы, и приложение в это время получает отказ в подключении.
Чтобы сервис ждал реальной готовности, у зависимости должен быть healthcheck, а в depends_on - условие condition: service_healthy, как в примере выше.

| Условие | Когда стартует зависимый сервис |
|---|---|
service_started (по умолчанию) |
сразу после запуска контейнера зависимости |
service_healthy |
когда healthcheck зависимости вернул успех |
service_completed_successfully |
когда зависимость завершилась с кодом 0, удобно для миграций |
Сборка своего образа
Если приложение ваше, вместо image укажите build. Пример для сервиса на Node.js, который собирается из Dockerfile в текущей папке и при разработке видит изменения кода:
services:
app:
build: .
ports:
- "3000:3000"
env_file: .env
volumes:
- ./src:/app/src
depends_on:
- redis
redis:
image: redis:7-alpine
После правки Dockerfile или зависимостей образ нужно пересобрать:
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 pull
docker compose up -d
Compose пересоздаст только те контейнеры, у которых изменился образ или настройки.
Переменные окружения и несколько файлов
Compose автоматически читает файл .env из папки проекта и подставляет значения в конструкции ${ИМЯ}. Можно задать значение по умолчанию: ${PORT:-8080}. Файл, указанный в env_file, наоборот, передаёт переменные внутрь контейнера, а не в сам compose.yaml. Эти два механизма часто путают.
Для разных окружений удобно держать базовый файл и файл с отличиями. Если рядом с compose.yaml лежит compose.override.yaml, Compose объединит их автоматически. Для продакшена файлы указывают явно:
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.





Комментарии
Комментариев пока нет - будьте первым.