Docker Compose: healthcheck e recuperação de serviços

Resposta rápida

Um processo vivo não significa que a aplicação esteja pronta. healthcheck executa uma verificação repetível dentro do container e marca o serviço como healthy ou unhealthy. Use esse sinal para diagnóstico e orquestração; não trate reinícios como prova de que o problema foi resolvido.

Veja a infraestrutura: VPS com monitoramento e backup semanal para colocar este projeto no ar.

O que um bom teste deve responder

Escolha uma verificação pequena e útil: uma rota /health, conexão a uma dependência essencial ou uma consulta simples. Não faça um teste que altere dados, dependa de um serviço externo instável ou consuma a mesma carga que a aplicação deveria atender.

Exemplo no Compose

services:
  app:
    image: exemplo/app:stable
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/health || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    restart: unless-stopped

Se a imagem não tem curl, use wget, um binário próprio ou uma verificação compatível com a distribuição. O start_period dá tempo para a aplicação inicializar sem marcar falha prematuramente.

Observe o resultado

docker compose up -d
docker compose ps
docker inspect --format '{{json .State.Health}}' nome-do-container
docker compose logs --tail=100 app

O histórico do healthcheck mostra código de saída e parte da saída do comando. Procure o primeiro erro, não apenas a última reinicialização.

Falha controlada

Em ambiente de teste, altere temporariamente a rota ou pare uma dependência e observe a transição para unhealthy. Depois restaure a condição e confirme que o serviço volta a responder. Não faça esse teste em produção sem janela, monitoramento e plano de rollback.

Armadilhas comuns

Um healthcheck que chama um endpoint autenticado pode falhar por credencial expirada. Um teste que depende de DNS público pode indicar falha da internet, não da aplicação. restart: unless-stopped ajuda a recuperar processo, mas não corrige migração quebrada, falta de disco ou configuração inválida.

Combine o healthcheck com logs, uso de CPU/RAM, espaço em disco e alertas externos. Uma VPS para Docker deve ter recursos e observabilidade compatíveis com os serviços que hospeda.

Checklist

• [ ] Health endpoint é barato e representativo.
• [ ] Comando existe na imagem.
• [ ] Timeout, retries e start period refletem o boot real.
• [ ] Falhas aparecem nos logs.
• [ ] Há procedimento de rollback.

FAQ

Healthcheck reinicia o container?

Por si só, ele apenas informa o estado. A política de reinício e a ferramenta de orquestração determinam a recuperação.

depends_on espera o serviço ficar saudável?

O comportamento depende da versão e da condição configurada. Valide a resolução usada pelo seu Compose em vez de assumir que a ordem de inicialização garante prontidão.

Exemplo de decisão

Se a aplicação leva 90 segundos para migrar o banco, um start_period de 20 segundos gera um alerta falso. Se a rota /health responde mesmo quando a fila está parada, ela é um teste fraco para o objetivo do serviço. Registre por que cada comando foi escolhido e qual falha ele deveria detectar. Esse pequeno documento ajuda a equipe a atualizar o healthcheck quando a aplicação muda, sem transformar um indicador operacional em decoração no Compose.