docker compose up: флаги -d, --build, --force-recreate и --no-deps на практике | AdminWiki

docker compose up: флаги -d, --build, --force-recreate и --no-deps на практике

18 ноября 2026 12 мин. чтения

Что делает 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 updocker 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 и находить причину ошибок

Вывод идёт по этапам, и по последнему этапу видно, где именно упало:

  1. чтение и валидация compose-файла: ошибки YAML, неизвестные ключи, неразрешённые переменные;
  2. сеть проекта: создание сети по умолчанию, если её ещё нет;
  3. сборка образов, если есть build или указан --build: шаги BuildKit с именами инструкций Dockerfile;
  4. создание контейнеров с именами, производными от имени проекта и сервиса;
  5. запуск контейнеров и, без -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.

Чек-лист перед запуском и пересозданием:

  1. Проверьте итоговую конфигурацию через docker compose config, особенно переменные окружения и порты.
  2. Убедитесь, что данные базы лежат в именованном томе или bind mount.
  3. После правок Dockerfile запускайте up -d --build, после правок только кода с bind mount достаточно перезапуска.
  4. Настройте healthcheck для сервисов, от готовности которых зависят другие, и condition: service_healthy в depends_on.
  5. После старта проверьте docker compose ps и docker compose logs -f, затем приложение по HTTP или порту.
  6. Перед docker compose down -v снимите дамп и проверьте восстановление.

Базовую структуру проекта с сервисами, сетями и секцией build разбираем в руководстве по Docker Compose для многоконтейнерных приложений. Начните с docker compose up -d --build, проверьте статусы и логи, а принудительное пересоздание применяйте только после того, как данные вынесены за пределы слоя контейнера.

Первоисточники

Поведение флагов и порядок запуска сервисов сверяйте с официальной документацией Docker Compose:

Поделиться: