App Healthcheck

O healthcheck path (também chamado de caminho do healthcheck ou endpoint de healthcheck) permite que a plataforma verifique periodicamente se sua aplicação está rodando corretamente.

Por padrão, se nenhum healthcheck estiver configurado, a plataforma executa apenas uma verificação básica após o deploy: ela valida se o container da aplicação iniciou com sucesso. Nesse caso, a saúde real da aplicação não é avaliada — o app pode estar respondendo incorretamente ou nem responder, e ainda assim o deploy será marcado como bem-sucedido.

Para evitar isso, você pode configurar um healthcheck path. Sua aplicação deve expor um endpoint que não dependa de sistemas externos (como banco de dados ou serviços de terceiros) e que reflita corretamente o estado interno da aplicação.

Você pode definir esse endpoint durante a configuração — por exemplo: /health, /status ou /ping.

Por padrão, durante o deploy o sistema verifica apenas a URL raiz (/). Ele envia uma requisição para a página principal e, se o status da resposta não estiver na faixa 2xx, o deploy é considerado mal-sucedido.

Como os healthchecks funcionam

• As requisições de healthcheck são sempre feitas a partir de localhost.

• O único requisito é que o endpoint retorne um status 2xx. O corpo da resposta não importa — apenas o status HTTP.

Durante o redeploy

Se um healthcheck path estiver configurado, o sistema envia até três requisições GET consecutivas para a nova instância da aplicação.

• Se ao menos uma requisição retornar status 2xx, o deploy é considerado bem-sucedido e a nova versão se torna ativa.

• Se todas as três tentativas falharem (qualquer status diferente de 2xx), o deploy é marcado como mal-sucedido e a versão anterior permanece ativa.

As verificações continuam até que uma das seguintes condições seja atendida:

• uma única resposta bem-sucedida;

• três respostas consecutivas com falha, sendo a última 40 segundos após o startup;

• ou o tempo limite de 180 segundos seja atingido.

Se nenhuma dessas condições for atendida dentro desse período, o deploy é considerado mal-sucedido.

Em caso de falha, uma mensagem de erro de healthcheck aparecerá nos logs de deploy.

Após o startup

Depois que o deploy é concluído com sucesso, o sistema continua verificando a saúde da aplicação com uma requisição a cada 30 segundos.

Se três verificações consecutivas falharem, a aplicação é reiniciada automaticamente. Esse evento será registrado nos logs da aplicação.

Configurando um Healthcheck Path

Você pode configurar o healthcheck path ao criar uma nova aplicação ou posteriormente, para uma aplicação existente.

Ao criar uma aplicação

Na seção Configurações do aplicativo, informe o caminho desejado no campo Caminho de Healthcheck.

Por exemplo, se sua aplicação expõe o endpoint /health acessível em https://domain.com/health, informe:

/health

Para uma aplicação existente

1. Abra a aplicação no painel de controle.

2. Vá até a aba Configurações.

3. Na seção Configurações de implantação, clique em Editar.

4. Informe o healthcheck path.

5. Clique em Salvar dados.

Um novo deploy será iniciado automaticamente com a configuração atualizada.

Docker e Docker Compose

Deploy via Dockerfile

Se sua aplicação for implantada usando um Dockerfile, você ainda pode configurar o healthcheck path pelo painel de controle.

No entanto, se o Dockerfile contiver uma instrução HEALTHCHECK, ela terá prioridade, e a configuração feita no painel será ignorada.

Exemplo:

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost/health || exit 1

Para mais detalhes, consulte a documentação oficial do Docker.

Deploy via Docker Compose

Para deploys com Docker Compose, a configuração do healthcheck path pelo painel de controle não é suportada.

Se seus serviços utilizarem um Dockerfile, você pode configurar o HEALTHCHECK diretamente nele — o comportamento será o mesmo descrito acima.