Checklist: healthcheck no Docker Compose para reiniciar app web

Healthcheck no Docker Compose é um mecanismo que verifica periodicamente se a aplicação dentro do container está respondendo, marcando o serviço como healthy ou unhealthy. Sozinho, ele não reinicia nada: o reinício automático vem da combinação com a política de restart e, quando necessário, um watcher como o autoheal. Para configurar, siga estes passos:

1. Defina o bloco healthcheck no serviço web do docker-compose.yml
2. Escolha um comando de teste real (curl, wget ou script interno)
3. Ajuste intervalo, timeout, retries e start_period
4. Combine com restart: unless-stopped ou always
5. Valide o status com docker compose ps
6. Monitore logs de falha e ajuste thresholds

Pré-requisitos para configurar healthcheck no Docker Compose

• Acesso SSH root ou sudo a um servidor Linux (Debian 13, Ubuntu 25.04 ou AlmaLinux 10)
• Docker Engine 27+ e Docker Compose v2 (plugin docker compose) instalados
• Arquivo docker-compose.yml já funcional com o serviço web
• Uma rota de teste na aplicação (ex: /health ou /) que responda HTTP 200
• Ferramenta de teste disponível dentro da imagem (curl, wget ou nc)
• Conhecimento básico de sintaxe YAML e indentação

Como funciona o healthcheck no Docker Compose

O healthcheck no Docker Compose executa um comando dentro do container em intervalos definidos e classifica o status como healthy, unhealthy ou starting. Diferente de um simples "processo rodando", o healthcheck valida se a aplicação de fato responde a requisições, o que é essencial para apps web que podem travar em deadlock, memory leak ou loop de erro 500 sem que o processo principal morra. Quando o container atinge unhealthy após o número de retries configurado, o Docker não mata o container automaticamente — é a política de restart combinada com orquestradores externos (ou o próprio Compose com depends_on: condition: service_healthy) que decide a ação. Entender essa distinção evita a frustração de configurar o healthcheck e esperar reinício automático que nunca vem sem o restart policy correto.

Sintaxe básica do healthcheck no Docker Compose

A estrutura mínima usa test, interval, timeout, retries e start_period. Veja um exemplo aplicado a um serviço Nginx servindo uma aplicação web:

services:
  web:
    image: nginx:1.28
    restart: unless-stopped
    ports:
      - "80:80"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s

Output esperado ao rodar docker compose ps:
NAME      IMAGE        STATUS
web       nginx:1.28   Up 2 minutes (healthy)

Checklist de configuração do healthcheck para reiniciar a aplicação web

Este checklist reúne os pontos que costumam ser esquecidos em produção. Siga cada item antes de considerar o healthcheck pronto para ambiente real.

1. O comando de test retorna código de saída 0 quando saudável e diferente de 0 quando falha — teste manualmente antes de colocar no YAML.
2. A imagem base contém curl ou wget; imagens Alpine minimalistas frequentemente não têm nenhum dos dois instalado.
3. O start_period é maior que o tempo real de boot da aplicação (Node.js, PHP-FPM, Java) para evitar falso positivo de "unhealthy" logo no início.
4. A política restart está definida como unless-stopped ou on-failure — sem isso, o status unhealthy fica apenas informativo.
5. Se usar múltiplos serviços dependentes, o depends_on usa condition: service_healthy em vez do formato simples de lista.
6. Logs do healthcheck foram inspecionados com docker inspect para confirmar a causa real de falhas.

Testando o healthcheck do Docker Compose manualmente

Antes de confiar no reinício automático, valide o comando de teste rodando-o diretamente dentro do container:

docker compose exec web curl -f http://localhost/health
echo $?

Output esperado:
{"status":"ok"}
0

Se o código de saída não for 0, o Docker Compose vai marcar o container como unhealthy mesmo que a aplicação esteja funcionando — geralmente por rota errada, porta incorreta ou ausência do binário de teste na imagem.

Usando healthcheck junto com restart policy para reinício automático

A política de restart é o componente que efetivamente reinicia o container quando o healthcheck reporta falha persistente. O Docker Compose sozinho, no modo standalone (sem Swarm), não reinicia containers apenas por estarem unhealthy — ele depende do processo interno morrer ou de você combinar com um watcher externo. Para simular reinício efetivo em ambiente sem orquestrador completo, uma abordagem comum é fazer o próprio processo da aplicação encerrar quando detectar falha interna, deixando o Docker cuidar do restart via política configurada.

services:
  app:
    build: .
    restart: on-failure:5
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:3000/health || exit 1"]
      interval: 20s
      timeout: 3s
      retries: 3
      start_period: 10s

Output esperado ao consultar docker inspect:
"Health": {
  "Status": "unhealthy",
  "FailingStreak": 3
}

Se o objetivo é reinício automático real ao ficar unhealthy em ambiente sem Swarm, considere um sidecar simples com autoheal (container que monitora status e roda docker restart nos que estiverem unhealthy) ou migre para Docker Swarm ou Kubernetes quando a criticidade exigir failover automático nativo. Se o serviço nem chega a subir no boot, veja como solucionar problemas de inicialização de serviços no VPS Linux.

Ajustando intervalo, timeout e retries para evitar falsos positivos

O ajuste fino de intervalo e timeout do healthcheck é o que separa um monitoramento confiável de reinícios em loop. Intervalos muito curtos (5s) geram carga extra na aplicação e podem confundir picos legítimos de latência com falha real. Timeouts muito baixos (1s) derrubam checks válidos em momentos de GC pesado no Java ou queries lentas no banco. Uma prática testada em produção com apps PHP-FPM ou Node.js é usar interval: 30s, timeout: 5s e retries: 3, o que dá até 90 segundos de tolerância antes de marcar como definitivamente unhealthy — suficiente para absorver picos transitórios sem mascarar falhas reais.

healthcheck:
  test: ["CMD-SHELL", "wget --spider -q http://localhost:8080/ || exit 1"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 20s

Para bancos de dados atrás da aplicação, vale revisar também o tempo de resposta das conexões ao MySQL, já que timeouts curtos no healthcheck da aplicação podem falhar em cascata se o banco estiver lento, mesmo com o app web saudável.

Problemas comuns e como resolver

Sintoma: container fica sempre "unhealthy" mesmo com a aplicação respondendo

Causa: a imagem não possui curl ou wget instalado, comum em imagens Alpine ou distroless.
Solução: troque o teste para usar utilitários nativos como nc -z localhost 80, ou instale curl na etapa de build da imagem com apk add curl.

Sintoma: container reinicia em loop constante após ficar unhealthy

Causa: start_period insuficiente combinado com restart: always, fazendo o container reiniciar antes mesmo da aplicação terminar de subir.
Solução: aumente o start_period para cobrir o tempo real de boot (medido com time docker compose up) e use restart: on-failure:5 para limitar tentativas.

Sintoma: healthcheck aparece como "starting" indefinidamente

Causa: o comando de teste está com sintaxe incorreta ou a rota testada retorna erro 404 por caminho errado.
Solução: execute o comando manualmente com docker compose exec e verifique o código de saída; confira também se a porta interna do teste coincide com a porta exposta pela aplicação.

Sintoma: docker compose ps não mostra coluna de status de saúde

Causa: versão antiga do Docker Compose ou ausência do bloco healthcheck no serviço correto do YAML.
Solução: atualize para Docker Compose v2 recente e confirme a indentação do bloco healthcheck dentro do serviço, não no nível raiz do arquivo.

Perguntas frequentes sobre healthcheck no Docker Compose

O Docker Compose reinicia o container automaticamente quando ele fica unhealthy?

Não diretamente. O status unhealthy é apenas informativo no modo standalone; o reinício efetivo depende da política restart combinada com o processo interno falhando, ou de uma ferramenta auxiliar como autoheal monitorando os containers.

Qual a diferença entre healthcheck e restart policy no Docker Compose?

O healthcheck apenas diagnostica se a aplicação está respondendo corretamente, enquanto a restart policy define o comportamento do Docker quando o container (o processo principal) para de rodar. Os dois precisam trabalhar juntos para reinício automático confiável.

Por que meu healthcheck funciona no terminal mas falha no Docker Compose?

Geralmente porque o comando testado no host usa ferramentas que não existem dentro do container, ou porque a URL testada aponta para localhost fora do container em vez do endereço interno correto do serviço.

Quanto tempo o Docker espera antes de marcar um container como unhealthy?

O tempo total é aproximadamente interval x retries, somado ao start_period inicial. Com interval: 30s e retries: 3, são cerca de 90 segundos de falhas consecutivas antes da marcação definitiva.

Healthcheck no Docker Compose funciona igual em produção e em Kubernetes?

Não. O Kubernetes usa probes próprias (livenessProbe e readinessProbe) com lógica de reinício nativa e mais robusta; o healthcheck do Compose é mais limitado e adequado principalmente para VPS com poucos serviços ou ambientes de staging.

Conclusão

• Configure o healthcheck com comando de teste validado manualmente antes de subir em produção
• Combine sempre com uma restart policy adequada — healthcheck sozinho não reinicia nada
• Ajuste interval, timeout e start_period conforme o comportamento real da sua aplicação, não valores genéricos copiados

Leia também

• Checklist para Configurar e Testar Limite de Upload no Webmail Horde em VPS Linux e Servidor Dedicado
• Checklist de Segurança no cPanel: Guia Prático e Completo
• Checklist de upload falhando no cPanel: causa e correção

Precisa de ajuda com Docker Compose no seu servidor?

Configurar healthcheck e políticas de restart corretamente exige um ambiente estável e com recursos previsíveis. Um VPS bem dimensionado facilita testes de carga e ajuste fino desses parâmetros sem surpresas de performance.

Conheça os planos de VPS da AviraHost