Como configurar um script de healthcheck para reiniciar containers travados no VPS

Como configurar um script de healthcheck para reiniciar containers travados no VPS

Oi! Aqui é a Sensei da GeHost 🥋 e hoje eu vou te ensinar uma mãozinha valiosa pra quem roda aplicações em containers (Docker) no seu VPS: um script de healthcheck. Ele fica de olho nos seus containers e, se algum "travar" (parar de responder, mas sem cair de vez), ele reinicia sozinho — sem você precisar acordar de madrugada pra dar um restart manual. Vamos com calma, passo a passo.

O que é um healthcheck, afinal?

Um container pode continuar "rodando" (o processo está de pé) mesmo travado por dentro — travou numa conexão de banco, ficou preso em memória, parou de responder requisições, etc. O Docker sozinho não sabe diferenciar isso de um container saudável, a menos que você ensine ele a checar. É exatamente isso que o healthcheck faz: testa periodicamente se o container está respondendo de verdade, e se não estiver, avisa (ou, com o nosso script, reinicia).

💡 Dica da Sensei: antes de sair reiniciando tudo automaticamente, é sempre bom entender por que o container está travando. Um restart automático é um bom curativo de emergência, mas se o problema se repete direto, vale investigar a causa (memória insuficiente, bug na aplicação, banco lento etc.).

Passo 1 — Acesse seu VPS via SSH

Conecte no seu servidor normalmente pelo terminal:

ssh usuario@seu-servidor

Se você tiver dúvida de qual usuário/porta usar no seu VPS, dá uma olhada nos dados de acesso que ficam no painel.gehost.com.br ou chama o suporte pra confirmar.

Passo 2 — Confira quais containers você tem rodando

Liste os containers ativos com:

docker ps

Anote o nome (ou o CONTAINER ID) dos containers que você quer monitorar. É esse nome que vamos usar no script.

Passo 3 — Garanta que o container tem um HEALTHCHECK definido

Pra esse tipo de monitoramento funcionar direitinho, o ideal é que a imagem/container já tenha uma diretiva de HEALTHCHECK configurada (no Dockerfile ou no docker-compose.yml). Um exemplo simples num docker-compose.yml:

services:
  minha-app:
    image: minha-imagem:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/"]
      interval: 30s
      timeout: 5s
      retries: 3

Isso faz o Docker testar a cada 30 segundos se a aplicação responde. Se falhar 3 vezes seguidas, o status do container vira unhealthy — e é esse status que nosso script vai vigiar.

📌 Sem HEALTHCHECK definido? Sem problema, o script ainda funciona checando se o container simplesmente parou de rodar (status exited), só que ele não vai pegar travamentos "silenciosos" (processo de pé, mas sem responder). Se puder, vale configurar o HEALTHCHECK — fica bem mais preciso.

Passo 4 — Crie o script de vigilância

Vamos criar um arquivo chamado healthcheck-monitor.sh. Pode usar o editor que preferir (nano, vim, etc.):

nano /root/healthcheck-monitor.sh

Cole este conteúdo, trocando meu-container pelo nome real do(s) seu(s) container(s):

#!/bin/bash

CONTAINERS=("meu-container" "outro-container")
LOG="/var/log/healthcheck-monitor.log"

for CONTAINER in "${CONTAINERS[@]}"; do
  STATUS=$(docker inspect --format='{{.State.Health.Status}}' "$CONTAINER" 2>/dev/null)

  if [ "$STATUS" == "unhealthy" ]; then
    echo "$(date '+%Y-%m-%d %H:%M:%S') - $CONTAINER está unhealthy, reiniciando..." >> "$LOG"
    docker restart "$CONTAINER" >> "$LOG" 2>&1
  fi

  # Caso o container tenha parado de vez (sem healthcheck definido)
  RUNNING=$(docker inspect --format='{{.State.Running}}' "$CONTAINER" 2>/dev/null)
  if [ "$RUNNING" == "false" ]; then
    echo "$(date '+%Y-%m-%d %H:%M:%S') - $CONTAINER está parado, iniciando..." >> "$LOG"
    docker start "$CONTAINER" >> "$LOG" 2>&1
  fi
done

Salve o arquivo e saia do editor.

Passo 5 — Dê permissão de execução

chmod +x /root/healthcheck-monitor.sh

Passo 6 — Teste manualmente

Antes de automatizar, rode o script uma vez na mão pra ver se está tudo certinho:

/root/healthcheck-monitor.sh
cat /var/log/healthcheck-monitor.log

Se o log aparecer vazio, é sinal de que nenhum container estava travado no momento do teste — ótimo sinal! Se algo travar de propósito (pode simular parando um processo dentro do container), você deve ver a linha de "reiniciando..." no log.

Passo 7 — Automatize com o cron

Agora vamos fazer esse script rodar sozinho de tempos em tempos. Edite o crontab:

crontab -e

E adicione uma linha pra rodar, por exemplo, a cada 5 minutos:

*/5 * * * * /root/healthcheck-monitor.sh

Salve e pronto — a partir de agora, a cada 5 minutos o servidor confere a saúde dos containers listados e reinicia quem estiver travado, sem você precisar fazer nada.

Passo 8 — Acompanhe o log de vez em quando

Vale o hábito de espiar o arquivo de log de vez em quando pra entender se algum container está travando com frequência:

tail -n 50 /var/log/healthcheck-monitor.log

Se um mesmo container aparece reiniciando toda hora, isso é um sinal de alerta — o restart automático está "tampando" um problema que merece ser investigado (uso de memória, configuração da aplicação, dependência externa, etc.).

🌱 Dica final da Sensei: reinício automático é uma rede de segurança, não uma solução definitiva. Ele evita que seu site/sistema fique fora do ar enquanto ninguém percebe — mas a causa raiz do travamento continua valendo a pena ser investigada com calma. Se precisar de uma mãozinha nessa investigação, é só chamar o suporte da GeHost pelo painel.gehost.com.br que a gente ajuda a entender o que está pegando. 💙