Что делает docker compose up и что означает флаг -d
docker compose up собирает, создаёт и запускает контейнеры сервисов, описанных в compose-файле, и подключается к ним. Если контейнеры уже запущены, команда дополнительно запускает связанные сервисы. Одна команда приводит стек к состоянию, которое записано в YAML, а повторный вызов не плодит дубликаты: compose сверяет желаемое состояние с текущим.
Флаг -d (detached mode) запускает контейнеры в фоне и оставляет их работающими. Compose стартует контейнеры и возвращает управление терминалу: команда завершается, контейнеры продолжают работать. Без -d сессия занята объединённым потоком логов всех сервисов, а Ctrl+C останавливает контейнеры.
Короткий ответ на частый вопрос «что такое docker compose up -d»: это штатный запуск стека в фоне. Логи после него смотрят отдельной командой, статус проверяют через docker compose ps.
Минимальный пример с приложением и базой:
services:
app:
build: .
ports:
- "8080:8080"
environment:
DB_HOST: db
depends_on:
- db
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
Запуск и проверка результата:
docker compose up -d docker compose ps docker compose logs -f app
Compose создаёт контейнеры, сеть проекта и том pgdata, если их ещё нет. Имена контейнеров и сети зависят от имени проекта: compose подставляет его в названия объектов, поэтому сверяйтесь с выводом docker compose ps, а не с ожидаемым шаблоном.
Чем отличается docker compose up от docker compose up -d
Разница не в наборе сервисов, а в том, как команда управляет терминалом и завершением процессов.
| Параметр | docker compose up | docker compose up -d |
|---|---|---|
| Терминал | Занят потоком логов | Свободен сразу после старта |
| Ctrl+C | Останавливает контейнеры | Ни на что не влияет |
| Логи | Идут в терминал в реальном времени | Читаются через docker compose logs -f |
| Типовой сценарий | Первый запуск, отладка падений на старте | Сервер, CI, повседневная работа |
В интерактивном режиме сразу видно, какой сервис падает и на каком шаге. Это удобно при первом разборе нового compose-файла: вывод подсказывает, где ошибка в конфигурации или в приложении. Для сервера такой режим неудобен: поток логов смешивается, а завершение клиента останавливает стек.
Смысл флага тот же, что у -d в docker run: процесс уходит в фон, а вы возвращаетесь в шелл. Разница между командами подробно разобрана в руководстве по docker run.
Рекомендация проста: отлаживайте без -d, а в остальных случаях поднимайте стек с -d и следите за логами отдельной командой. Остановить такой стек можно через docker compose stop, а не через Ctrl+C в другом окне.
Как проверить, что сервисы действительно запустились
После up -d compose печатает короткий отчёт о создании и старте контейнеров и завершается. Дальше состояние проверяют тремя командами:
- docker compose ps показывает имя контейнера, сервис, статус и проброс портов;
- docker compose ps -a добавляет остановленные контейнеры и их exit code;
- docker compose logs -f app транслирует логи конкретного сервиса, docker compose top показывает процессы внутри контейнеров.
Статус Up говорит только о том, что процесс запущен. Готовность приложения он не подтверждает: веб-сервер может подняться раньше, чем применит миграции или подключится к базе. Проверяйте приложение по существу, например запросом к health-эндпоинту:
curl -fsS http://localhost:8080/health
Если эндпоинта нет, добавьте healthcheck в compose-файл. Тогда docker compose ps покажет статус (healthy) или (unhealthy):
services:
app:
build: .
ports:
- "8080:8080"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
interval: 10s
timeout: 3s
retries: 5
start_period: 20s
curl должен присутствовать в образе. В минимальных образах на базе alpine или distroless его нет, и healthcheck будет падать по причине, не связанной с приложением. start_period даёт процессу время на инициализацию, чтобы первые неудачные проверки не переводили контейнер в unhealthy.
Флаг --build: когда нужно пересобирать образы
docker compose up берёт готовый образ, если он есть локально. Правки в Dockerfile или в файлах, которые копируются в образ, сами по себе ничего не меняют: compose запустит прежний образ, потому что тег остался тем же. Флаг --build собирает образы перед запуском контейнеров.
Пересборка нужна в таких случаях:
- изменился Dockerfile: инструкции, порядок слоёв, набор пакетов;
- изменились файлы, которые попадают в образ через COPY или ADD;
- нужно подтянуть свежую версию базового образа, для этого сборку запускают с docker compose build --pull;
- изменились build args, влияющие на сборку.
Если код монтируется в контейнер через bind mount, пересборка часто не нужна: правки видны сразу, достаточно перезапустить процесс. Пересборка требуется, когда меняется само окружение образа, а не исходники.
Две команды решают разные задачи. docker compose build только собирает образы и ничего не запускает. docker compose up --build собирает и сразу поднимает стек. В CI удобнее разделять этапы: сначала build, затем up -d, иначе ошибка сборки проявится уже после попытки запуска.
# пересборка и запуск всех сервисов docker compose up -d --build # пересборка и запуск одного сервиса docker compose up -d --build app
Скорость пересборки определяет кэш слоёв: Docker переиспользует слой, пока не изменилась инструкция и её контекст. Поэтому зависимости ставят отдельным слоем до копирования исходников, а редко меняющиеся файлы копируют раньше остальных. Как это устроено на практике, разобрано в статье про слои, кэширование и multi-stage build.
Пересоздание контейнеров: --force-recreate, --no-recreate и когда compose делает это сам
При up compose сравнивает конфигурацию сервиса из файла с параметрами существующего контейнера. Изменились образ, переменные окружения, порты, команда или тома, контейнер пересоздаётся: старый удаляется, новый создаётся из актуальной конфигурации. Если ничего не менялось, контейнер остаётся работать как есть.
--force-recreate пересоздаёт контейнеры, даже если их конфигурация и образ не менялись. Флаг нужен, когда состояние контейнера залипло: процесс не подхватил новое значение из env_file, внутри остались временные файлы, перезапуска недостаточно. --no-recreate работает наоборот: compose запускает существующие контейнеры и не пересоздаёт их, даже если файл изменился. Это страховка от сброса состояния на живом стенде. Два флага несовместимы: --no-recreate нельзя сочетать с --force-recreate.
При пересоздании контейнеров compose сохраняет смонтированные тома. Данные при этом ведут себя по-разному:
| Где лежат данные | Судьба при пересоздании |
|---|---|
| Именованный том (pgdata) | Сохраняются, удаляются только через docker compose down -v или docker volume rm |
| Bind mount с хоста | Сохраняются, файлы остаются в файловой системе хоста |
| Анонимный том | Не имеет стабильного имени, поэтому при последующем up автоматически не монтируется; для сохранения данных используйте именованный том или bind mount |
| Файлы в слое контейнера | Теряются: слой удаляется вместе со старым контейнером |
Перед принудительным пересозданием проверьте, что всё ценное вынесено в именованный том или bind mount. Всё, что приложение пишет внутрь слоя контейнера, исчезнет.
docker compose up -d --force-recreate app
Порядок запуска и depends_on: что гарантирует и чего не гарантирует
depends_on задаёт порядок запуска и остановки: compose стартует и останавливает контейнеры в порядке зависимостей. Но при запуске compose не ждёт, пока контейнер станет «готовым», а ждёт только его запуска. Postgres инициализирует кластер несколько секунд, и приложение, поднятое сразу после создания контейнера базы, получит отказ в подключении.
Для определения готовности используется атрибут condition с тремя опциями: service_started (эквивалент короткого синтаксиса depends_on), service_healthy (зависимость должна пройти healthcheck) и service_completed_successfully (зависимость должна успешно завершиться, подходит для миграций и одноразовых задач). Атрибут condition в depends_on появился в Docker Compose 2.17.0, поэтому на более старых версиях он не сработает. Проверьте версию через docker compose version.
services:
app:
build: .
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 10
Здесь app стартует только после того, как pg_isready внутри контейнера базы отработает успешно. Ограничение остаётся: healthcheck подтверждает готовность принимать подключения, но не отменяет сетевые сбои и перезапуски базы во время работы приложения. Ретраи подключения в коде приложения и разумный restart: on-failure закрывают эту гонку, healthcheck её только сужает.
Комбинация флагов: что означает docker compose up -d build и как запускать отдельные сервисы
Запрос «docker compose up -d build» обычно означает команду docker compose up -d --build. Отдельного аргумента build у up нет. Если выполнить docker compose up -d build дословно, compose примет build за имя сервиса и завершится ошибкой о том, что такого сервиса нет. Правильная запись включает флаг с двумя дефисами.
| Флаг | Что делает | Когда нужен |
|---|---|---|
| -d | Фоновый режим | Сервер, CI, ежедневная работа |
| --build | Собирает образы перед запуском | Правки Dockerfile или файлов внутри образа |
| --force-recreate | Пересоздаёт контейнеры, даже если конфигурация и образ не менялись | Не подхватились переменные окружения, залипло состояние |
| --no-recreate | Не пересоздавать существующие контейнеры | Нельзя терять текущее состояние стенда |
| --no-deps | Не запускает связанные сервисы | База уже работает отдельно или в другом проекте |
Типовой сценарий с пересборкой: поправили Dockerfile, выполнили docker compose up -d --build, дождались пересоздания контейнера и проверили версию приложения.
Флаг --no-deps запускает указанный сервис, не создавая и не поднимая его зависимости:
docker compose up -d --no-deps --build app
Приём полезен, когда база живёт на отдельном хосте или в другом compose-проекте, и когда нужно быстро пересобрать один сервис в уже работающем стеке. Риск очевиден: если db не запущена, app поднимется и упадёт на подключении. Команда docker compose up -d app без --no-deps поднимает сервис вместе с зависимостями.
Как читать вывод docker compose up и находить причину ошибок
Вывод идёт по этапам, и по последнему этапу видно, где именно упало:
- чтение и валидация compose-файла: ошибки YAML, неизвестные ключи, неразрешённые переменные;
- сеть проекта: создание сети по умолчанию, если её ещё нет;
- сборка образов, если есть build или указан --build: шаги BuildKit с именами инструкций Dockerfile;
- создание контейнеров с именами, производными от имени проекта и сервиса;
- запуск контейнеров и, без -d, привязка потоков логов.
Ошибка сборки проявляется на шаге Dockerfile: контейнер ещё не создан, в выводе видно, какая инструкция упала. Как читать такие сообщения, разобрано в статье про docker build и вывод BuildKit. Ошибка запуска выглядит иначе: контейнер создан, но завершился, в docker compose ps -a виден статус Exited и код возврата.
docker compose ps -a docker compose logs --tail=100 app docker compose config
docker compose config показывает итоговую конфигурацию после подстановки переменных и объединения нескольких файлов. Это быстрый способ проверить, какое значение реально получил сервис. Вывод содержит переменные из .env в открытом виде, поэтому не пересылайте его во внешние тикеты без вычитки.
Код возврата 137 обычно означает принудительное завершение процесса, например срабатывание OOM killer. Код 1 указывает на ошибку самого приложения, её причину ищут в логах сервиса, а не в compose-файле.
Конфликт портов распознаётся по ошибке bind на этапе создания контейнера: порт уже занят другим процессом или контейнером. Проверьте занятость через docker ps и ss -ltnp, затем смените внешний порт в маппинге или остановите конфликтующий контейнер.
Жизненный цикл контейнеров при up и связь с down, stop и restart
Последовательность при up такая: create (создание контейнера из образа с конфигурацией), start (запуск процесса), recreate при изменённой конфигурации, stop при остановке, down при удалении. Повторный up идемпотентен: он не создаёт второй комплект контейнеров, а приводит существующие к нужному состоянию.
| Команда | Контейнеры | Сети | Именованные тома |
|---|---|---|---|
| docker compose up -d | Создаёт, запускает, пересоздаёт при изменениях | Создаёт при отсутствии | Сохраняются |
| docker compose stop | Останавливает, контейнеры остаются | Остаются | Сохраняются |
| docker compose start | Запускает остановленные | Не меняет | Сохраняются |
| docker compose restart | Перезапускает процесс без пересоздания | Не меняет | Сохраняются |
| docker compose down | Останавливает и удаляет | Удаляет сети из секции networks и сеть по умолчанию | Сохраняются |
| docker compose down -v | Останавливает и удаляет | Удаляет | Удаляет именованные и анонимные тома |
docker compose restart не применяет правки compose-файла: конфигурация контейнера остаётся прежней, для изменений нужен up. Обратная ситуация с down -v: команда удаляет именованные тома из секции volumes и анонимные тома, присоединённые к контейнерам, вместе с данными базы. Перед её запуском снимите дамп, проверьте, что он восстанавливается, и только затем удаляйте тома.
Типичные ошибки и практические сценарии
Готовые комбинации под частые задачи:
# первый запуск проекта: собрать образы и поднять стек docker compose up -d --build # разработка с bind mount: код уже смонтирован в контейнер docker compose up -d # после правки Dockerfile docker compose up -d --build # контейнер работает со старым значением переменной окружения docker compose up -d --force-recreate app # пересобрать один сервис, не трогая зависимости docker compose up -d --no-deps --build app
Частые ошибки и их признаки:
- Забыли --build после правки Dockerfile. Признак: код или пакеты в контейнере старые, docker compose ps показывает прежний образ.
- Ждут готовности базы от depends_on. Признак: app падает с ошибкой подключения при старте, хотя контейнер db запущен.
- Запускают up без -d на сервере. Признак: стек останавливается вместе с клиентом, логи смешаны в одну сессию.
- Делают --force-recreate, не вынеся данные в том. Признак: после пересоздания база пустая, файлы в слое контейнера пропали.
- Рассчитывают, что restart применит правки compose-файла. Признак: конфигурация осталась прежней, изменений нет.
- Смотрят только на сообщение о старте контейнеров. Признак: сервис числится запущенным, но не отвечает, потому что контейнер уже завершился. Проверяется через docker compose ps -a.
Чек-лист перед запуском и пересозданием:
- Проверьте итоговую конфигурацию через docker compose config, особенно переменные окружения и порты.
- Убедитесь, что данные базы лежат в именованном томе или bind mount.
- После правок Dockerfile запускайте up -d --build, после правок только кода с bind mount достаточно перезапуска.
- Настройте healthcheck для сервисов, от готовности которых зависят другие, и condition: service_healthy в depends_on.
- После старта проверьте docker compose ps и docker compose logs -f, затем приложение по HTTP или порту.
- Перед docker compose down -v снимите дамп и проверьте восстановление.
Базовую структуру проекта с сервисами, сетями и секцией build разбираем в руководстве по Docker Compose для многоконтейнерных приложений. Начните с docker compose up -d --build, проверьте статусы и логи, а принудительное пересоздание применяйте только после того, как данные вынесены за пределы слоя контейнера.
Первоисточники
Поведение флагов и порядок запуска сервисов сверяйте с официальной документацией Docker Compose:
- docker compose up — справочник CLI: описание -d, --build, --force-recreate, --no-recreate и сохранения смонтированных томов при пересоздании.
- Control startup and shutdown order in Compose: depends_on, condition и опции service_started, service_healthy, service_completed_successfully.
- Compose file: services: синтаксис depends_on и версия, в которой появился атрибут condition.
- docker compose down — справочник CLI: что удаляется по умолчанию, поведение анонимных томов и флага -v.