Uptime Kuma no homelab: saber que caiu antes da família

Quando um serviço do homelab cai, quero saber antes de alguém da família reclamar. A ferramenta que mais aparece quando o assunto é esse é o Uptime Kuma, e foi olhando para ela que eu desenvolvi o meu próprio monitor, o Sonar, com algumas melhorias e alguns pontos de que eu precisava. Para a velocidade e a estabilidade da internet, uso outro app, o Pingularity.

Neste post explico o que o Uptime Kuma monitora, como instalar e o que eu configuraria primeiro, pela documentação do projeto. No fim, mostro como ficou o Sonar.

O que é o Uptime Kuma #

É uma ferramenta de monitoramento self-hosted, com licença MIT. Você cadastra o que quer vigiar, e ele testa de tempos em tempos e avisa quando algo para de responder.

Pela página do projeto, ele monitora:

• HTTP(s), inclusive procurando uma palavra na página (HTTP(s) Keyword);
• TCP, para qualquer porta;
• ping;
• registro de DNS;
• containers Docker;
• WebSocket e servidores de jogos Steam;
• push: em vez de o Kuma perguntar, o serviço é que avisa o Kuma que está vivo.

E avisa por mais de 90 serviços de notificação, entre eles Telegram, Discord, Slack, Gotify, Pushover e e-mail por SMTP.

Outros recursos listados pelo projeto que importam num homelab:

• testes a cada 20 segundos, no intervalo mais curto;
• informações do certificado HTTPS de cada site;
• autenticação em dois fatores para entrar no painel;
• várias páginas de status, cada uma com o seu domínio, se quiser.

Instalando #

Há dois caminhos que fazem sentido num Proxmox.

Pelo community-scripts. O script do Uptime Kuma cria um container LXC Debian 13 unprivileged, com 1 núcleo, 1 GB de RAM e 4 GB de disco por padrão. Como contei no post sobre o community-scripts, eu leio o script antes de rodar, porque ele roda como root no host.

Por Docker. O comando da documentação do projeto:

docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

A interface fica na porta 3001. A tag :2 é a da versão 2.

Sem Docker, a instalação manual pede Node.js 20.4 ou mais novo, Git e o PM2 para rodar em segundo plano. Como quase tudo aqui é LXC e uso pouco o Docker, o caminho do community-scripts combina mais com o meu homelab.

Onde colocar o monitor #

Um detalhe que pesa: o monitor não pode cair junto com o que ele monitora.

Se o Uptime Kuma roda no mesmo Proxmox dos serviços, ele avisa quando um container para. Mas se o host inteiro cair, ou a energia, ou a internet, o Kuma cai junto e ninguém avisa nada.

Para esse caso há duas saídas:

• rodar o Kuma em outra máquina, de preferência fora de casa;
• usar o monitor do tipo push ao contrário: um serviço externo espera um sinal periódico do homelab e avisa quando o sinal para de chegar.

Para começar, um Kuma dentro do homelab já resolve a maior parte dos casos: container parado, serviço travado, página respondendo com erro.

O que eu monitoraria primeiro #

Pensando nos serviços que rodam aqui, a ordem seria:

1. Vaultwarden: monitor HTTP(s) na página de login. É o cofre de senhas da família, conto como montei no post sobre o Vaultwarden.
2. DNS interno: monitor do tipo DNS, perguntando por um nome interno ao Technitium. Se ele cai, a casa toda fica sem internet.
3. Este blog: HTTP(s) Keyword, procurando um texto que só aparece quando a página carrega certo.
4. Serviços publicados pelo Cloudflare Tunnel: testar pelo endereço público mostra se o tunnel está de pé, não só o serviço.

Página de status #

O Uptime Kuma também monta páginas de status: uma página pública com o estado dos serviços que você escolher. Num homelab de família, é uma forma de alguém em casa conferir se “a internet caiu ou foi só o app” sem me chamar.

Se for publicar a página de status, publique só ela. O painel de administração não precisa ficar aberto na internet. E, mesmo dentro de casa, ligue o segundo fator no login: quem entra no painel vê o mapa inteiro dos seus serviços.

O meu Sonar #

O Uptime Kuma serviu de base para o que eu queria. Mas eu precisava de algumas coisas do meu jeito, então escrevi o meu próprio monitor, o Sonar. A tela inicial dele é assim:

Algumas escolhas que dá para ver na tela:

• Unidades e links. Em vez de uma lista solta de monitores, cada unidade agrupa os seus links. Na imagem são 13 unidades e 25 links, e o próprio blog aparece dentro da unidade Self-Hosted!.
• Uma frase no topo. A primeira coisa que aparece é a resposta: “Todas as 13 unidades operando”. Se algo cai, é isso que muda.
• Quatro estados. Operando, em atenção, com link DOWN e fora do ar. Uma unidade que perdeu um link não é o mesmo que uma unidade inteira fora do ar.
• A última hora em blocos. Cada bloco é um minuto, com a latência ao lado. Dá para ver de relance se houve oscilação.
• Atualização automática, com o horário da última checagem e um botão para atualizar na hora.

Se você está começando, o Uptime Kuma resolve muito bem. Escrever o próprio monitor só vale quando você já sabe exatamente o que quer ver na tela.

Resumindo #

• Uptime Kuma monitora HTTP(s), TCP, ping, DNS, Docker e push, com mais de 90 tipos de notificação.
• Instalação pelo community-scripts (LXC Debian 13, 1 núcleo, 1 GB de RAM) ou por Docker, na porta 3001.
• Nada de NFS para a pasta de dados.
• O monitor cai junto com o host. Para quedas de energia e internet, é preciso algo fora de casa.
• Comece pequeno: cofre de senhas, DNS e os serviços públicos.
• Monitor próprio só quando você já sabe o que quer. O meu Sonar nasceu olhando para o Uptime Kuma.

Saber que algo caiu antes da família perceber é metade do trabalho de manter um homelab. A outra metade é ter o backup para consertar.

Tags: uptime-kuma, monitoramento, self-hosted, docker