Monitore seu ambiente e serviços com Uptime Kuma: Instalação e Configuração

Como você monitora se o seu serviço está online? Como demonstra ao cliente que seu sistema teve 99,9% de disponibilidade nos últimos 30 dias? E, mais importante: como notificá-lo em caso de indisponibilidade?
Essas são perguntas que o Uptime Kuma ajuda a responder. Trata-se de uma ferramenta open source que permite criar uma página pública (ou privada) de status dos seus serviços, além de configurar alertas de forma simples e eficaz.

Neste artigo, vamos mostrar como instalar, configurar e explorar os principais recursos do Uptime Kuma. E já adiantamos: dá pra fazer muita coisa de forma simples

Pré Requisitos

O Uptime Kuma roda atualmente via Docker, portanto, é necessário tê-lo instalado previamente no servidor. Outro ponto importante é a forma de acesso: caso deseje utilizar um domínio, será necessário configurar um proxy. A documentação oficial oferece suporte para: Nginx, Apache, Caddy, Traefik, Cloudflare Tunnel, OpenLiteSpeed e HAProxy.
Para este tutorial, vamos utilizar o Cloudflare Tunnel.

Optamos pelo Cloudflare Tunnel devido a uma limitação do Uptime Kuma: atualmente, ele permite apenas uma conta para gerenciar e cadastrar endereços. Se quiser utilizar mais de uma conta, o gerenciamento precisa ser feito pelo próprio Cloudflare. Inclusive, já escrevemos um artigo sobre isso: Como expor servidores com Cloudflare Tunnel sem abrir portas no firewall

Instalando o Uptime Kuma

Com os pré-requisitos atendidos, a instalação pode ser feita de duas formas: utilizando um banco de dados interno (padrão) ou um banco externo. Para simplificar, usaremos o banco interno.

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

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

Após a execução, verifique se o container está rodando com:

docker ps
# ou
docker container ls

docker ps
# ou
docker container ls

Em seguida, acesse http://localhost:3001/setup para criar sua conta de administrador.

Acessando via domínio com Cloudflare Tunnel

Como mencionamos anteriormente, o objetivo é acessar a página de status via um domínio, como status.codeinloop.com.br. Para isso, usaremos o Cloudflare Tunnel como proxy reverso. Além de garantir o acesso via domínio público, ele também nos permite criar múltiplas contas de administrador, superando a limitação do Kuma de uma conta única.

Siga o tutorial indicado até a etapa “Instalação do cloudflared no Ubuntu”.

Com o token do túnel em mãos:

• No Uptime Kuma, clique no seu avatar (canto superior direito) e vá em Configurações.
• No menu lateral, acesse Proxy Reverso.
• Cole o token gerado no campo correspondente e clique em Iniciar cloudflared.

Uma vez conectado, retorne à interface do Cloudflare para configurar o domínio:

• tipo: http
• url: localhost:3001

Você deve ver algo como:

Considerações sobre autenticação

Agora sua página de status já pode ser acessada publicamente via domínio. Existem dois caminhos possíveis:

• Modo simples: um único login administrativo, com a página pública acessível a todos.
• Modo multiusuário: múltiplos administradores com login individual, mantendo a página pública ou protegida.

Neste tutorial, manteremos o fluxo simples. Caso precise proteger o acesso, siga o tutorial do Cloudflare até a seção “Protegendo com autenticação via Cloudflare Access”.

Configurando seus primeiros monitores

Antes de criar seu primeiro monitor, é importante entender os tipos de monitoramento que o Uptime Kuma oferece. A ferramenta suporta desde verificações simples, como ping ou HTTP, até integrações mais específicas com bancos de dados, containers e serviços em nuvem. Esses tipos estão organizados em três grandes categorias:

Monitoramento Geral

• HTTP(s): Verifica se uma URL está respondendo com sucesso.
• TCP Port: Checa se uma porta específica está aberta em um host.
• Ping: Envia pacotes ICMP para validar se o host responde.
• Palavra-Chave (HTTP): Verifica a presença de um termo específico no corpo da resposta.
• JSON Query (HTTP): Permite validar o conteúdo de uma resposta JSON.
• gRPC Palavra-Chave: Similar ao anterior, mas para serviços gRPC.
• DNS: Realiza consultas DNS e valida a resposta.
• Container Docker: Monitora se um container está em execução.
• HTTP com Browser Engine (Beta): Usa o Chrome/Chromium real para validar se a página carrega corretamente (ideal para apps SPA ou com JavaScript pesado).

Monitoramento Passivo

• Push: Ideal para aplicações que notificam ativamente o Kuma (via API) em vez de serem verificadas.

Monitoramento Específico

• Steam/GameDig: Verifica servidores de jogos online.
• MQTT
• Kafka Producer
• SQL Server
• PostgreSQL
• MySQL/MariaDB
• MongoDB
• Redis
• Radius

Criando seu primeiro monitor: Verificando o blog do Code in Loop

Para começar, vamos configurar um monitor simples que verifica se o blog do Code in Loop está online. Como não temos uma página de healthcheck dedicada no momento, apenas validaremos se a URL retorna um código HTTP 200.

Siga os passos:

1. Clique em “Adicionar novo monitor”.
2. No campo Tipo, selecione HTTP(s).
3. Preencha os campos:
   • Nome amigável: Blog Code in Loop
   • URL: https://codeinloop.com.br
4. Clique em Salvar.

Pronto! Seu primeiro monitor estará ativo e o Uptime Kuma começará a validar periodicamente a disponibilidade da URL.

A interface exibirá o histórico de checagens, tempo de resposta, status atual e — caso configure — notificações de falhas.

Criando uma página de status

Agora que já temos um serviço sendo monitorado, podemos criar nossa página de status pública, que exibirá a disponibilidade atual dos serviços monitorados.

Para isso:

1. No dashboard do Uptime Kuma, acesse o menu “Páginas de status”.
2. Clique em “Nova página de status”.
3. Defina:
   • Nome: um título descritivo para a página (ex: Status Code in Loop).
   • Slug: o identificador usado na URL (ex: codeinloop).

Após isso, você será redirecionado para o construtor da página, onde pode:

• Agrupar serviços em seções;
• Adicionar uma descrição;
• Personalizar estilos com CSS.

Para este exemplo, vamos manter simples e adicionar apenas o nosso primeiro monitor configurado.

A página estará disponível em:

👉 https://status.codeinloop.com.br/status/codeinloop

Essa URL pode ser compartilhada com seu time ou com clientes para acompanhar a saúde dos serviços monitorados em tempo real.

Configurando notificações (Telegram, Discord, E-mail, teams…)

Agora vem um dos pontos centrais do monitoramento: o que fazer quando algo que não deveria acontecer, acontece?
Por exemplo: quem deve ser notificado quando um serviço cair?

No Uptime Kuma, é possível configurar notificações personalizadas acessando o menu “Configurações”. Essas notificações podem ser aplicadas globalmente (para todos os monitores) ou de forma segmentada por grupo — o que é útil para cenários em que o Time A cuida de um conjunto de serviços e o Time B de outro.

Para este exemplo, vamos configurar notificações via Telegram, mas vale destacar que o Uptime Kuma tem suporte nativo para dezenas de provedores, e esse número salta para mais de 50 com o uso da biblioteca Apprise.

Configurando provedor de notificação via Telegram

Já abordamos esse processo em outro artigo, portanto recomendamos a leitura de:
📄 Como configurar notificações do GitLab no Telegram — até o tópico “Obtendo o ID do chat no Telegram”.

Uma vez que o provedor esteja configurado corretamente, o Uptime Kuma enviará notificações automáticas sempre que o serviço apresentar falhas ou retornar à normalidade, como no exemplo abaixo:

Configurando manutenção programada

Agora que seu time e seus clientes já podem ser notificados quando um serviço sair do ar, surge uma nova necessidade: evitar alertas desnecessários em situações previstas, como em casos de manutenção programada.

Nem sempre queremos notificar todo mundo que um serviço está offline — especialmente se isso estiver dentro de uma janela planejada. Para isso, o Uptime Kuma oferece a funcionalidade de agendamento de manutenção, disponível no dashboard em “Agendar manutenção”.

Essa funcionalidade garante que:

• A página de status exibirá uma mensagem informando a manutenção;
• Nenhuma notificação será enviada durante esse período.

Como agendar uma manutenção

Na tela de agendamento, preencha os seguintes campos:

• Título: Nome da manutenção (ex: Atualização do blog);
• Descrição: Explicação breve do que será feito;
• Serviços ou páginas afetadas: Escolha quais monitores estarão em manutenção (ex: Blog Code in Loop);
• Data e hora: Defina o início e término da janela;
• Fuso horário: Selecione o correto para seu time;
• Recorrência (opcional): Caso a manutenção aconteça em ciclos regulares (ex: toda segunda-feira às 22h).

Com isso, o Uptime Kuma desativará os alertas automaticamente dentro da janela definida, evitando ruído para a equipe e para os usuários finais.

Conclusão

Com poucos passos, é possível estruturar uma solução de monitoramento funcional e visualmente acessível, sem depender de ferramentas pagas ou complexas. Ficou com alguma dúvida ou tem uma sugestão de monitoramento avançado? Deixe seu comentário abaixo, vamos trocar ideias!