Як працює HEALTHCHECK і як написати добру перевірку стану?

Docker за замовчуванням знає лише, чи працює процес. Процес може бути живим, але застосунок - завислим: зайняті всі воркери, втрачено з'єднання з базою, вичерпано пам'ять. HEALTHCHECK дає змогу перевіряти справжню готовність.

HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
  CMD curl -fsS http://localhost/up || exit 1

Параметри:

• --interval - як часто перевіряти (за замовчуванням 30 с);
• --timeout - скільки чекати на відповідь;
• --start-period - час на запуск, протягом якого невдачі не рахуються (прогрів, міграції);
• --start-interval - частіші перевірки протягом стартового періоду, щоб швидше стати «здоровим»;
• --retries - скільки невдач поспіль до статусу unhealthy.

Команда повертає 0 - здоровий, 1 - нездоровий. Статус видно в docker ps (healthy, unhealthy, starting).

Хто використовує статус:

• Compose: depends_on з condition: service_healthy - сервіс стартує, коли залежність справді готова;
• Swarm замінює нездорові контейнери і не перемикає трафік на новий контейнер під час оновлення, доки той не здоровий;
• платформи деплою (Dokploy, Coolify, Kamal) чекають на здоровий контейнер перед перемиканням трафіку.

Сам Docker Engine не перезапускає нездоровий контейнер - статус лише позначається. Перезапуск робить оркестратор чи власна логіка.

Яка перевірка добра:

• легка й швидка: запит на /up (у Laravel 11+ такий маршрут є за замовчуванням), а не тяжка сторінка з запитами до бази;
• перевіряє застосунок, а не лише порт: відповідь саме від PHP, а не лише від Nginx;
• глибина - свідомий вибір: перевірка бази в healthcheck означає, що короткочасна недоступність бази позначить нездоровими всі контейнери застосунку - і оркестратор почне їх перезапускати, погіршуючи ситуацію. Часто краще перевіряти лише сам застосунок;
• наявні утиліти: у мінімальних образах немає curl - тоді wget -q --spider, вбудована команда застосунку чи невеликий бінарник.

Для воркерів без HTTP (черги, планувальник) - перевірка процесу чи файлу-маркера, який воркер оновлює («серцебиття»).

Перевизначити чи вимкнути - у Compose: healthcheck: у сервісі чи disable: true.

Докладніше в документації: Dockerfile: HEALTHCHECK