Quando um site, uma API ou um servidor para de responder, descobrir pelo usuário é tarde demais. O Uptime Kuma é uma ferramenta de monitoramento self-hosted com interface web: ela executa verificações em intervalos regulares, registra o histórico e envia alertas quando um serviço muda de estado. Neste guia, vamos instalá-lo com Docker Compose, publicá-lo com Nginx e configurar os primeiros monitores com segurança.
Por que usar o Uptime Kuma
O Kuma faz sentido quando você precisa saber rapidamente se algo que o usuário consome continua acessível: um site, uma API, uma porta TCP, uma resolução DNS ou a conclusão de um job. Ele reúne a checagem, o histórico, a mudança de estado, a notificação e uma página de status em uma interface simples. Como é self-hosted, URLs, credenciais de notificação e histórico ficam na sua infraestrutura, em vez de em uma conta de monitoramento de terceiros.
Isso não o torna uma substituição universal. Uptime não é observabilidade completa: um endpoint pode responder e ainda estar lento, sem espaço em disco ou com uma fila acumulada. A melhor escolha é usá-lo como a camada de disponibilidade e alerta rápido, ao lado de métricas e logs quando a operação precisar de diagnóstico profundo.
Em que linguagem ele é desenvolvido
O Uptime Kuma é uma aplicação para Node.js, predominantemente em JavaScript. A interface web usa Vue 3 e Vite; o repositório também inclui TypeScript na cadeia de desenvolvimento. Por isso a execução sem Docker exige Node.js 20.4 ou superior, mas o caminho com contêiner evita instalar Node e dependências do projeto diretamente no host.
O que o Uptime Kuma monitora
O projeto é uma alternativa leve para acompanhar a disponibilidade de serviços sem terceirizar o painel. Ele suporta monitores HTTP(S), TCP, busca de palavra-chave e consulta JSON em HTTP(S), WebSocket, ping, DNS, push, servidores Steam e contêineres Docker. Também oferece páginas públicas de status, gráfico de latência, informações de certificado, suporte a proxy, autenticação em dois fatores e integrações de notificação.
Ele não substitui métricas detalhadas: para CPU, memória, disco e séries temporais de servidores, combine-o com o Prometheus e Node Exporter. O Kuma responde a outra pergunta: “este endpoint está acessível agora e alguém foi avisado?”.
Instale Docker, Compose e Nginx no Ubuntu
Os comandos abaixo são para Ubuntu 22.04 LTS, 24.04 LTS ou posterior suportado pelo Docker. Eles usam o repositório oficial do Docker, que entrega o Engine e o plugin moderno docker compose. Em uma máquina que já roda contêineres, não remova nem substitua pacotes sem revisar o impacto: a documentação do Docker lista docker.io, docker-compose, containerd e runc entre os pacotes que podem conflitar com a instalação oficial.
Em um host novo, instale os pré-requisitos, o Nginx e a chave do repositório:
sudo apt update
sudo apt install -y ca-certificates curl nginx
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg
-o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.ascAdicione a fonte APT. O comando lê automaticamente o codinome e a arquitetura da instalação atual:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt updateInstale o Docker Engine, o Compose e ative os serviços:
sudo apt install -y docker-ce docker-ce-cli containerd.io
docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker nginx
sudo docker run hello-world
docker compose versionO primeiro comando de teste baixa uma imagem pequena e encerra; ele confirma que o daemon funciona. Mantenha sudo nos comandos Docker ou configure o acesso pós-instalação conscientemente: pertencer ao grupo docker equivale, na prática, a poder administrativo sobre o host. Antes de expor portas de contêiner, revise também o firewall: regras publicadas pelo Docker podem contornar regras do UFW.
Antes de começar
Você precisa de um host Linux com Docker Engine e o plugin Docker Compose. O exemplo usa um diretório próprio em /opt, um volume local para os dados e a porta do serviço limitada a 127.0.0.1. Assim, a interface não fica aberta diretamente na internet; o Nginx será a única porta de entrada.
O banco de dados do Uptime Kuma fica no diretório de dados. Não coloque esse diretório em NFS: o projeto não o suporta, porque os bloqueios de arquivo necessários pelo SQLite não são adequados nesse cenário. Inclua /opt/uptime-kuma/data no backup do servidor.
Suba o Uptime Kuma com Docker Compose
Crie o diretório e o arquivo compose.yaml:
sudo install -d -m 0755 /opt/uptime-kuma
sudoedit /opt/uptime-kuma/compose.yamlUse esta configuração. A tag :2 acompanha a versão mais recente da linha 2 e é a recomendada pelo projeto. Para congelar uma release específica, use uma tag 2.x.x. Não use :latest como atalho para a versão 2: esse nome está depreciado e ainda aponta para a linha 1.
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
- "127.0.0.1:3001:3001"Inicie e confirme o estado:
cd /opt/uptime-kuma
sudo docker compose up -d
sudo docker compose ps
curl -I http://127.0.0.1:3001Na primeira abertura, crie a conta administrativa. Guarde essa senha em um gerenciador de senhas e habilite 2FA nas configurações. Para acompanhar a inicialização, use sudo docker compose logs -f.
Publique com Nginx e HTTPS
Escolha um subdomínio, por exemplo status-admin.exemplo.com, e aponte o DNS para o servidor. O Uptime Kuma deve ficar na raiz desse subdomínio; ele não oferece suporte a instalação em subdiretório como exemplo.com/kuma/.
Primeiro, emita um certificado TLS para o subdomínio pelo método adotado no seu servidor. Não abra a interface nem crie a conta administrativa antes de o HTTPS estar ativo: login por HTTP expõe a credencial. Depois, crie o server block final. Ajuste os caminhos do certificado ao seu ambiente; o suporte a WebSocket é importante para que a interface atualize em tempo real:
server {
listen 80;
server_name status-admin.exemplo.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name status-admin.exemplo.com;
ssl_certificate /etc/letsencrypt/live/status-admin.exemplo.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/status-admin.exemplo.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Teste antes de recarregar:
sudo nginx -t
sudo systemctl reload nginxValide https://status-admin.exemplo.com e só então faça o primeiro login. Ao ativar a opção Trust Proxy no Kuma, faça isso somente se toda requisição chegar por um proxy reverso que você controla; caso contrário, cabeçalhos encaminhados podem falsificar o IP de origem. Para uma revisão de Nginx no Debian ou Ubuntu, veja nosso guia sobre Nginx e versões de PHP.
Crie monitores que realmente avisam algo útil
No painel, clique em Add New Monitor. Comece com poucos checks que representem uma jornada real:
- HTTP(S): a URL pública do site ou da API. Defina os códigos HTTP aceitos conforme a aplicação.
- Keyword: uma página de saúde que precise conter um marcador conhecido, como
ok. - TCP: a porta de um serviço que deve aceitar conexão, como SMTP ou uma aplicação interna.
- DNS: um registro crítico, útil para detectar erro de resolução ou mudança inesperada.
- Push: jobs de backup, sincronização ou manutenção: o job chama a URL exclusiva fornecida pelo Kuma quando termina. Se o sinal não chegar dentro da janela configurada, o monitor fica em alerta.
Evite intervalos agressivos por padrão. Um monitor com muitos falsos positivos é rapidamente ignorado. Defina timeout, tentativas e intervalo de acordo com a criticidade e com a capacidade do serviço monitorado.
Configure notificações antes da falha
Abra Settings → Notifications, cadastre o canal escolhido e use o botão de teste. O Uptime Kuma tem integrações para SMTP, Telegram, Discord, Slack, Gotify, Pushover e diversos outros serviços. Depois, associe a notificação a cada monitor — criar o canal sozinho não envia alertas.
Comece com uma rota que alguém realmente acompanhe. Para serviço crítico, use mais de um destino e documente quem responde a cada tipo de alerta.
Página pública de status, sem expor a administração
Em Status Pages, crie uma página com os monitores que podem ser mostrados ao público. Ela é separada do painel administrativo: publique apenas o que é apropriado revelar. Uma página de status é útil para reduzir chamados durante uma indisponibilidade, mas não deve listar serviços internos, endereços privados ou detalhes de infraestrutura.
Atualização e backup
Faça backup do diretório de dados antes de atualizar. Em uma janela de manutenção, o fluxo básico é:
cd /opt/uptime-kuma
sudo docker compose pull
sudo docker compose up -d --force-recreate
sudo docker compose logs --tail=100Confira as notas de versão oficiais antes de atualizar, principalmente em mudanças de versão principal. O projeto mantém também uma orientação específica para a migração da v1 para a v2.
Cuidados de segurança
- Não publique a porta
3001diretamente; mantenha-a em127.0.0.1atrás de HTTPS e autenticação. - Use senha exclusiva, 2FA e atualizações regulares.
- Proteja o backup de
data: ele pode conter URLs, tokens de notificação e informações sobre sua infraestrutura. - O monitor de contêineres pode exigir acesso ao socket Docker. Esse socket controla o daemon; não o monte sem entender o impacto e nunca trate essa instância como um painel público.
Alternativas: qual usar em cada cenário
- Gatus: monitoramento self-hosted escrito em Go e definido em arquivo de configuração. É uma boa opção para times que preferem revisar checks no Git e aplicar configuração como código.
- Prometheus com Blackbox Exporter: coleta métricas de probes HTTP, TCP, ICMP e DNS e integra alertas ao ecossistema Prometheus. Escolha-o quando os dados precisam virar séries temporais, dashboards e regras mais sofisticadas.
- Zabbix: plataforma mais ampla para hosts, rede, descoberta e templates. Vale para inventários maiores; para poucos endpoints, costuma exigir mais operação que o Kuma.
- Cachet: é focado em comunicação de incidentes e página pública de status. Pode complementar um monitor, mas não deve ser escolhido sozinho esperando o mesmo conjunto de probes do Kuma.
Em resumo: escolha o Kuma pela interface rápida e pelo conjunto de checks prontos; Gatus para configuração versionada; Prometheus/Blackbox para métricas e alertas como código; e Zabbix quando a necessidade é monitorar a infraestrutura inteira.
Onde o Kuma entra na sua operação
O Uptime Kuma é excelente como camada simples de disponibilidade e alerta: um painel para seus endpoints, jobs e páginas de status. Para monitoramento profundo de hosts, complete a estratégia com Prometheus; para conhecer alternativas tradicionais, confira as histórias do Nagios e do Zabbix. A instalação oficial, a configuração avançada de proxy e o código-fonte estão no repositório do Uptime Kuma.