Como fazer self-host do Uptime Kuma em 2026: alertas, TLS e dados persistentes

A maioria das instruções de instalação do Uptime Kuma termina no primeiro carregamento da página. Isso é cedo demais: o volume de dados pode estar em modo somente leitura ou o DNS do container pode não conseguir resolver os hosts monitorados. Um teste de produção útil é mais exigente: criar monitores HTTP e TCP, provocar uma falha controlada e receber o alerta e a notificação de recuperação pelo provedor escolhido.

O papel do Uptime Kuma é simples: monitorar serviços existentes e enviar alertas para mais de 90 destinos. Seu escopo operacional vai além do processo web, portanto a dependência, o estado armazenado e a rota pública precisam ser especificados antes que dados reais sejam gravados.

Defina primeiro o que significa sucesso para o Uptime Kuma

Um diagrama útil do Uptime Kuma mostra a rota pública, a porta privada 3001, o limite do estado e todos os requisitos de suporte. Marque quais setas transportam credenciais e quais representam tráfego comum de usuários. O requisito externo do Uptime Kuma é ter acesso de saída a todos os endpoints monitorados e provedores de alertas. Teste o DNS de saída, o TLS e o comportamento do provedor sem publicar outro serviço de entrada.

Comprove o diagrama com uma ação real: crie monitores HTTP e TCP, provoque uma falha controlada e receba o alerta e a notificação de recuperação pelo provedor escolhido. A maior pressão provavelmente virá do intervalo dos monitores, da quantidade de retries, do tráfego da página de status e do número de probes de saída feitos no mesmo segundo; monitore esse caminho em vez de tratar todas as requisições HTTP como equivalentes.

Opere o Uptime Kuma considerando seu gargalo real

A primeira métrica operacional útil do Uptime Kuma é verificar se ele consegue criar monitores HTTP e TCP, provocar uma falha controlada e enviar o alerta e a notificação de recuperação pelo provedor escolhido. Combine isso com sinais de saturação do intervalo dos monitores, da quantidade de retries, do tráfego da página de status e do número de probes de saída feitos no mesmo segundo. Um probe que verifica apenas o processo não deve chamar dependências caras nem reiniciar o container porque um upstream ficou temporariamente indisponível.

Trate os upgrades como alterações de dados, pois as migrações do SQLite e as mudanças nos provedores de notificações podem transformar um simples pull de imagem em um upgrade de aplicação com estado. Fixe as versões, faça ensaios com o estado restaurado e mantenha a imagem anterior disponível enquanto o rollback continuar válido. Quando o volume de dados estiver em modo somente leitura ou o DNS do container não conseguir resolver os hosts monitorados, preserve os logs anteriores ao restart; eles geralmente contêm a mensagem que explica a causa.

Registre uma implantação conhecida como funcional do Uptime Kuma

Para o Uptime Kuma, defina uma transação conhecida como funcional antes do lançamento: crie monitores HTTP e TCP, provoque uma falha controlada e receba o alerta e a notificação de recuperação pelo provedor escolhido. Registre seus pré-requisitos, a resposta esperada e as etapas de limpeza no version control, sem incluir valores secretos. Fixe a imagem usada para estabelecer essa referência.

Use a transação para validar uma substituição e um restore independente. O serviço restaurado só é aceitável quando o histórico dos monitores, as credenciais de notificação e as janelas de manutenção reaparecem e um alerta de teste é entregue. Ao mesmo tempo, observe o intervalo dos monitores, a quantidade de retries, o tráfego da página de status e o número de probes de saída feitos no mesmo segundo, transformando a parte mais lenta ou mais limitada em um alerta de nível de serviço.

O gate também precisa de um caso negativo: negue temporariamente o caminho de teste usado pelo acesso de saída a todos os endpoints monitorados e provedores de alertas. Confirme que o Uptime Kuma produz um erro acionável enquanto preserva os dados, restaure a condição válida e repita a transação conhecida como funcional. Manter os dois resultados impede que um endpoint de health superficial se torne a única evidência em produção.

Configurações do container que vale a pena revisar

Use o container como um runtime substituível, não como a fonte da verdade.

docker run -d \
  --name uptime-kuma \
  --restart unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma-data:/app/data \
  -e UPTIME_KUMA_PORT=3001 \
  louislam/uptime-kuma:1

Permita e verifique o caminho de saída ou do lado do cliente necessário para acessar todos os endpoints monitorados e provedores de alertas. Inspecione o usuário do container, os caminhos com permissão de escrita e o listener associado antes de expô-lo. Execute a ação completa — crie monitores HTTP e TCP, provoque uma falha controlada e receba o alerta e a notificação de recuperação pelo provedor escolhido — e salve a referência exata da imagem que produziu o resultado.

Restaure o Uptime Kuma em um host vazio

Proteja o estado do Uptime Kuma antes de otimizar o container. O conjunto necessário é o banco de dados SQLite e os assets enviados pelo usuário em /app/data. Monte /app/data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Se vários stores precisarem permanecer consistentes, documente a ordem em que as gravações são pausadas e os backups são feitos.

Mantenha cópias fora do servidor de deployment e criptografe o material que contenha credenciais ou conteúdo privado. A recuperação é bem-sucedida quando o histórico dos monitores, as credenciais de notificação e as janelas de manutenção reaparecem e um alerta de teste é entregue. A diferença entre um mount persistente e uma cópia independente é explicada em armazenamento persistente e snapshots.

Dê ao Uptime Kuma um endereço canônico

Publique uma única origem HTTPS estável por meio do reverse proxy. Aponte o hostname escolhido para a porta 3001 do container, encaminhe o host original e o esquema HTTPS e evite publicar uma segunda origem direta.

Teste o Uptime Kuma a partir de um cliente externo limpo. Separe uma falha de ingress do limite conhecido da aplicação — o volume de dados está em modo somente leitura ou o DNS do container não consegue resolver os hosts monitorados. Um erro de certificado, DNS ou 502 pertence ao roteamento; uma requisição que chega ao Uptime Kuma e falha depois pertence ao estado da aplicação, à capacidade ou a um requisito de suporte. O guia de TLS para domínios personalizados aborda o primeiro grupo.

Decisões de segurança específicas do Uptime Kuma

O risco de segurança específico da aplicação é executar a configuração do primeiro usuário em uma instância exposta publicamente. A abordagem operacional é concluir a configuração do primeiro usuário em ambiente privado e, depois, proteger separadamente os dashboards e a administração da página de status. Conclua o bootstrap por uma rota restrita e remova imediatamente o acesso temporário de configuração.

UPTIME_KUMA_PORT controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do Uptime Kuma separadamente. Dê ao processo do Uptime Kuma apenas os mounts e as rotas de dependência documentados; evite o acesso ao root do host e ao Docker socket. Registre falhas de autenticação e erros de configuração, mas redija tokens, connection strings e conteúdo do usuário.

Um deployment no Dockup ainda precisa de um teste de aceitação do Uptime Kuma

Roteamento, certificados, substituição de serviços e armazenamento anexado são alvos razoáveis para automação. O Dockup cuida desses aspectos para o Uptime Kuma e pode provisionar o banco de dados gerenciado relacionado ou conectar-se a serviços no próprio servidor do cliente.

O que ele não deve inventar é a política de confiança do Uptime Kuma. Após o deployment, publique uma única origem HTTPS estável por meio do reverse proxy, aplique este limite — conclua a configuração do primeiro usuário em ambiente privado e, depois, proteja separadamente os dashboards e a administração da página de status — e verifique o resultado deste cenário: crie monitores HTTP e TCP, provoque uma falha controlada e receba o alerta e a notificação de recuperação pelo provedor escolhido. O resultado é uma infraestrutura com um clique e um teste de aceitação específico da aplicação.

Perguntas frequentes

O que o Uptime Kuma precisa para um deployment em produção?

Encaminhe o container do Uptime Kuma na porta 3001 por meio de uma única origem HTTPS. O requisito externo de entrega é ter acesso de saída a todos os endpoints monitorados e provedores de alertas. Não considere o Uptime Kuma pronto até conseguir criar monitores HTTP e TCP, provocar uma falha controlada e receber o alerta e a notificação de recuperação pelo provedor escolhido.

Quais dados do Uptime Kuma devem fazer parte de um backup?

Mantenha /app/data persistente e inclua o banco de dados SQLite e os assets enviados pelo usuário em /app/data no mesmo manifesto de recuperação. Um restore limpo do Uptime Kuma só é aprovado quando o histórico dos monitores, as credenciais de notificação e as janelas de manutenção reaparecem e um alerta de teste é entregue.

O Uptime Kuma precisa de HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Uptime Kuma e mantenha a porta 3001 na rota interna. Aplique corretamente a configuração do Uptime Kuma: publique uma única origem HTTPS estável por meio do reverse proxy. No Uptime Kuma, o HTTPS protege credenciais ou conteúdo do usuário durante o transporte e mantém consistente o comportamento do cliente que depende da origem.

Como testar um upgrade do Uptime Kuma?

Restaure o estado atual do Uptime Kuma em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois as migrações do SQLite e as mudanças nos provedores de notificações podem transformar um simples pull de imagem em um upgrade de aplicação com estado. Mantenha a imagem anterior do Uptime Kuma até entender os limites da migração de dados e do rollback.