Como fazer self-host do Healthchecks em 2026: pings de cron, alertas e backups do banco de dados

Fazer self-host do Healthchecks se torna interessante no primeiro redeploy, não no primeiro docker run. Se os jobs de cron enviam ping para uma URL interna ou os workers de e-mail não estão em execução, o Docker ainda pode informar que o processo está perfeitamente saudável. A implantação abaixo é organizada em torno de um comportamento observável: enviar pings de início, sucesso e falha a partir de um job de teste, depois omitir um ping agendado e receber o alerta de job ausente.

A finalidade do Healthchecks é explícita: monitoramento dead-man para jobs de cron e tarefas em background. Essa descrição indica o que precisa permanecer público, o que deve continuar privado e o que um backup precisa reconstruir.

Faça backup do estado que o Healthchecks não consegue recriar

O container padrão do Healthchecks não exige um mount de dados da aplicação. Ainda assim, o conjunto necessário para recuperação é explícito: o banco de dados da aplicação e a configuração de notificações. Não crie um volume vazio apenas para fazer a implantação parecer stateful; preserve a referência exata da imagem e a configuração revisada.

Reconstrua o Healthchecks em um host vazio e execute a transação de aceitação. A recuperação é aprovada quando checks, schedules, integrações e chaves de ping retornam e um ping intencionalmente ausente gera o alerta esperado. Qualquer banco de dados conectado ou serviço de colaboração segue seu próprio plano de backup consistente com a aplicação, enquanto o container web substituível é recriado a partir do código. O guia de implantação do Git à produção descreve esse limite reprodutível.

Mantenha um checksum ou digest da imagem conhecida como válida e faça novos testes após as atualizações. Para um serviço stateless, uma reconstrução bem-sucedida é o teste de restore; para estado externo, o runbook do Healthchecks deve apontar para o responsável e o procedimento de recuperação separados.

Crie um container substituível do Healthchecks

Use um comando que exponha todas as escolhas importantes. Esta configuração básica vincula o Healthchecks ao loopback do host, adiciona os mounts de dados conhecidos e fornece a primeira configuração obrigatória. Adicione as configurações de conexão revisadas para Postgres e a entrega funcional de e-mail para alertas de produção; use nomes privados para serviços privados.

docker run -d \
  --name healthchecks \
  --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -e SECRET_KEY=replace-with-a-long-random-value \
  -e SITE_ROOT=https://app.example.com \
  -e ALLOWED_HOSTS=app.example.com \
  -e DB=postgres \
  -e DB_HOST=postgres.internal \
  -e DB_NAME=healthchecks \
  -e DB_USER=healthchecks \
  -e DB_PASSWORD=replace-with-a-strong-database-password \
  healthchecks/healthchecks:latest

Substitua tags flutuantes por uma versão testada ou um digest. Após a inicialização, inspecione docker logs --tail 200 healthchecks e confirme que o processo está escutando na porta 8000. Em seguida, execute a ação de aceitação do Healthchecks; uma resposta da página inicial não comprova que o cenário completo funciona: envie pings de início, sucesso e falha a partir de um job de teste, depois omita um ping agendado e receba o alerta de job ausente.

Do que o Healthchecks depende

Defina três limites ao redor do Healthchecks: entrada na porta 8000, estado durável e requisitos de suporte. O container é substituível, mas os outros dois precisam de responsáveis explícitos. O contrato de rede do Healthchecks é Postgres e a entrega funcional de e-mail para alertas de produção. Mantenha endpoints privados no DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Healthchecks uma credencial de serviço com escopo restrito.

O diagrama está completo quando um cliente limpo consegue enviar pings de início, sucesso e falha a partir de um job de teste, depois omitir um ping agendado e receber o alerta de job ausente. Registre dados de tempo e recursos referentes ao número de checks, períodos de tolerância, distribuição de notificações, entrega de e-mail e gravações no banco de dados. Se a transação falhar, o primeiro limite que não se comportar conforme documentado indicará se é preciso investigar roteamento, capacidade local ou um serviço de suporte.

Encaminhe o Healthchecks sem criar uma falsa impressão sobre HTTPS

Escolha o hostname final do Healthchecks antes que os usuários salvem callbacks ou configurações de cliente e, em seguida, defina SITE_ROOT e ALLOWED_HOSTS com o endereço HTTPS externo. A rota da plataforma deve terminar o TLS uma única vez e apontar para a porta privada 8000.

Execute a transação de aceitação externamente. Se o cliente nunca alcançar o Healthchecks, use a checklist de validação de SSL para verificar DNS e certificado. Se a requisição chegar ao Healthchecks, mas os jobs de cron enviarem ping para uma URL interna ou os workers de e-mail não estiverem em execução, pare de alterar redirects do proxy e inspecione o limite específico da aplicação.

Evidências a coletar antes de colocar o Healthchecks em produção

Crie um fixture pequeno e descartável do Healthchecks e mantenha-o para cada release. O fixture deve exercitar o workflow real: enviar pings de início, sucesso e falha a partir de um job de teste, depois omitir um ping agendado e receber o alerta de job ausente. Registre o digest da imagem, o hostname externo, o endereço da dependência e o resultado esperado para que outro operador possa repetir o teste posteriormente sem precisar interpretar este guia.

Execute o fixture três vezes. Primeiro, use a implantação recém-criada. Segundo, substitua o container sem tocar no estado durável. Terceiro, restaure o backup em um ambiente vazio. A terceira execução só é aprovada quando checks, schedules, integrações e chaves de ping retornam e um ping intencionalmente ausente gera o alerta esperado. Durante cada execução, capture latência e uso de recursos relacionados ao número de checks, períodos de tolerância, distribuição de notificações, entrega de e-mail e gravações no banco de dados; isso se torna a baseline dos alertas, em vez de um percentual arbitrário de CPU.

Por fim, teste deliberadamente o caminho negativo: negue temporariamente à identidade de teste o acesso ao Postgres e à entrega funcional de e-mail para alertas de produção. Confirme que o Healthchecks falha de forma visível sem corromper o estado, restaure a condição correta e repita a transação bem-sucedida. Um registro de release contendo esses quatro resultados é uma evidência mais forte do que screenshots de um dashboard ou uma resposta única de curl.

Simulações de falha do Healthchecks

Observe o trabalho realizado pelo Healthchecks: número de checks, períodos de tolerância, distribuição de notificações, entrega de e-mail e gravações no banco de dados. Defina limites com margem para esse trabalho e evite uma liveness probe que dispute recursos com ele. A verificação do operador ainda deve tentar enviar pings de início, sucesso e falha a partir de um job de teste, depois omitir um ping agendado e receber o alerta de job ausente conforme um schedule.

Para atualizações, lembre-se de que as migrations da aplicação e a configuração dos workers precisam ser atualizadas em conjunto para que a página web não oculte uma entrega de alertas quebrada. Faça o deploy do candidato sobre uma cópia recuperada e repita o teste conhecido. Se os jobs de cron enviarem ping para uma URL interna ou os workers de e-mail não estiverem em execução, use os logs de runtime e a requisição de rede real para descobrir qual suposição mudou.

Escolha o limite de confiança do Healthchecks

Feche a janela de bootstrap assim que existir o primeiro administrador confiável. A armadilha concreta do Healthchecks é usar um secret gerado que muda a cada reinicialização; o limite mais seguro é usar uma SECRET_KEY estável, restringir a participação em projetos e tratar URLs de ping como credenciais.

Gere SECRET_KEY uma única vez, mantenha-a fora do Git e preserve-a com o manifesto de recuperação, pois alterá-la pode invalidar o estado criptografado ou assinado da aplicação. A rede privada deve transportar as credenciais das dependências, e as roles dentro do Healthchecks devem conceder apenas a ação útil mínima. Mantenha corpos de requisição sensíveis e respostas de provedores fora dos logs rotineiros.

Uma implantação no Dockup ainda precisa de um teste de aceitação do Healthchecks

O Dockup pode gerenciar os componentes substituíveis da plataforma: encaminhar o tráfego para a porta 8000, emitir o domínio e o certificado, injetar secrets, anexar armazenamento persistente e conectar o Healthchecks a serviços gerenciados ou anexados de forma privada. Isso pode ser feito na infraestrutura do Dockup ou em um servidor que você conectar.

O trabalho de aceitação do Healthchecks continua explícito. Após a implantação em um clique, defina SITE_ROOT e ALLOWED_HOSTS com o endereço HTTPS externo, conecte e teste o Postgres e a entrega funcional de e-mail para alertas de produção e execute este cenário: envie pings de início, sucesso e falha a partir de um job de teste, depois omita um ping agendado e receba o alerta de job ausente. Essa divisão é intencional: o Dockup elimina a configuração repetitiva de infraestrutura sem fingir que roles da aplicação, credenciais de provedores ou política de restore se escolhem sozinhas.

Perguntas frequentes

O que o Healthchecks precisa para uma implantação em produção?

Encaminhe o container do Healthchecks na porta 8000 por meio de uma única origem HTTPS. O requisito de rede de suporte é Postgres e a entrega funcional de e-mail para alertas de produção. Não considere o Healthchecks pronto até conseguir enviar pings de início, sucesso e falha a partir de um job de teste, depois omitir um ping agendado e receber o alerta de job ausente.

Quais dados do Healthchecks devem fazer parte de um backup?

A imagem padrão do Healthchecks não possui um mount de dados da aplicação obrigatório. Preserve a configuração da implantação e faça backup de qualquer estado conectado separadamente; a recuperação é aprovada quando checks, schedules, integrações e chaves de ping retornam e um ping intencionalmente ausente gera o alerta esperado.

O Healthchecks precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Healthchecks e mantenha a porta 8000 na rota interna. Aplique corretamente a configuração do Healthchecks: defina SITE_ROOT e ALLOWED_HOSTS com o endereço HTTPS externo. Para o Healthchecks, o HTTPS protege credenciais ou conteúdo de usuários em trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Healthchecks?

Restaure o estado atual do Healthchecks em uma implantação isolada, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois as migrations da aplicação e a configuração dos workers precisam ser atualizadas em conjunto para que a página web não oculte uma entrega de alertas quebrada. Mantenha a imagem anterior do Healthchecks até compreender os limites de migração de dados e rollback.