Как управлять порядком запуска через depends_on и healthcheck
На этой странице
depends_on в короткой форме (depends_on: [db]) лишь гарантирует, что контейнер db запущен раньше api, — но не что PostgreSQL уже принимает подключения. Чтобы дождаться готовности, нужна длинная форма с условием: service_healthy (зависимость прошла healthcheck) или service_completed_successfully (одноразовая задача вроде миграций завершилась с кодом 0). Даже так приложение должно уметь переподключаться: база может перезапуститься в любой момент.
Вопрос
Как в Compose запустить сервисы в правильном порядке и дождаться готовности зависимостей?
Короткая форма — только порядок
services:
api:
build: .
depends_on:
- db
db:
image: postgres:18Compose создаст и запустит db раньше api. Но PostgreSQL инициализируется несколько секунд, и api может упасть с ECONNREFUSED.
Длинная форма — готовность
services:
api:
build: .
depends_on:
db:
condition: service_healthy
restart: true # перезапустить api, если db перезапустили через Compose
redis:
condition: service_started
db:
image: postgres:18
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
POSTGRES_DB: app
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 5s
timeout: 3s
retries: 10
start_period: 10s
redis:
image: redis:8-alpine| Условие | Ждёт |
|---|---|
service_started | Контейнер запущен (поведение короткой формы) |
service_healthy | Healthcheck зависимости вернул healthy |
service_completed_successfully | Зависимость завершилась с кодом 0 |
Если зависимость так и не стала healthy, docker compose up завершится с ошибкой — это лучше, чем API, который молча работает без базы.
Миграции перед стартом
services:
migrate:
build: .
command: ["npx", "prisma", "migrate", "deploy"]
depends_on:
db:
condition: service_healthy
api:
build: .
depends_on:
migrate:
condition: service_completed_successfullydb (healthy) ──▶ migrate (exit 0) ──▶ apiОстановка
При docker compose down и stop порядок обратный: сначала api, потом db. Так API успевает закрыть соединения до остановки базы.
Почему приложению всё равно нужен retry
depends_on работает только при запуске через Compose. Он не поможет, если:
- база перезапустилась через час работы;
- сеть кратковременно пропала;
- в production используется другая платформа, не знающая про
depends_on.
Поэтому клиент БД настраивают с повторными подключениями и экспоненциальной задержкой, а healthcheck API помечает сервис unhealthy, пока соединения нет.
Старые решения
Раньше в command добавляли скрипты wait-for-it.sh или dockerize, которые опрашивали порт. С условиями service_healthy это обычно не нужно — к тому же открытый порт не означает, что база готова.
Частые ошибки
- Считать, что
depends_on: [db]ждёт готовности. - Указать
service_healthyбез healthcheck у зависимости — Compose выдаст ошибку. - Запускать миграции в
commandкаждой реплики API. - Полагаться только на Compose и не писать логику переподключения.
Что важно помнить
- Порядок ≠ готовность; готовность даёт только healthcheck.
service_completed_successfully— способ встроить одноразовые задачи (миграции, seed) в граф запуска.restart: trueвdepends_onперезапускает зависимый сервис при перезапуске зависимости через Compose.
Мини-шпаргалка
depends_on: [db]— только порядок.condition: service_healthy+healthcheck— готовность.condition: service_completed_successfully— миграции.- Остановка — в обратном порядке.
- Retry в коде обязателен.
Документация
Docker: Control startup and shutdown order, Docker Compose: depends_on.