Como instalar Uptime Kuma com Docker Compose para monitorar sites, portas, ping e certificados SSL, com alertas no Telegram e página de status.
Para que serve
Ao instalar Uptime Kuma, você ganha uma ferramenta open source e auto-hospedada para checar, de tempos em tempos, se algo está respondendo: um site (HTTP/HTTPS, inclusive procurando uma palavra na página), uma porta TCP (RDP 3389, SQL 1433, SSH 22), um ping, um registro DNS, um container Docker ou a validade do certificado SSL. Quando algo cai ou volta, ele avisa por Telegram, e-mail, Discord, Slack, webhook e dezenas de outros canais. Também gera páginas de status públicas para seus clientes.
Neste artigo você vai instalar Uptime Kuma com Docker Compose e criar os primeiros monitores. É bem mais simples que um Zabbix: não mede CPU ou disco por dentro do servidor, mas responde rápido à pergunta "está no ar?".
Onde instalar
Pré-requisitos
- Uma máquina Linux com Docker e Docker Compose (veja o artigo «Como instalar Docker no Ubuntu e no Debian (com Docker Compose, pelo repositório oficial)»), ou um container LXC/VM pequeno no Proxmox (1 vCPU e 512 MB a 1 GB de RAM bastam para dezenas de monitores).
- Opcional: um domínio e um proxy reverso com HTTPS para acessar o painel.
Passo a passo para instalar Uptime Kuma
- Crie o projeto Compose:
A tagmkdir -p ~/apps/uptime-kuma && cd ~/apps/uptime-kuma cat > compose.yaml <<'EOF' services: uptime-kuma: image: louislam/uptime-kuma:2 container_name: uptime-kuma restart: unless-stopped ports: - "127.0.0.1:3001:3001" volumes: - ./data:/app/data EOF docker compose up -d:2acompanha a versão 2.x. A porta foi publicada só no localhost: o acesso externo deve passar por um proxy reverso com HTTPS ou por VPN/túnel SSH (lembre que o Docker ignora o UFW; veja o artigo «Docker ignora o UFW: por que acontece e como corrigir o firewall»). - Acesse o painel. Por túnel:
ssh -L 3001:127.0.0.1:3001 usuario@IPe abrahttp://localhost:3001. No primeiro acesso, escolha o banco (o SQLite embutido atende bem a maioria dos casos) e crie o usuário administrador. - Ative a autenticação em dois fatores em Settings → Security.
- Configure uma notificação em Settings → Notifications → Setup Notification. Para Telegram, informe o token do bot e o chat ID (o artigo «Como receber alertas do servidor no Telegram, e-mail ou WhatsApp» explica como obtê-los) e clique em Test. Marque Default enabled para aplicá-la a novos monitores.
- Crie os monitores em Add New Monitor. Sugestões para um servidor dedicado com Proxmox:
Um intervalo de 60 segundos com 2 ou 3 tentativas (Retries) antes de alertar evita falsos positivos por oscilação momentânea.O que vigiar Tipo de monitor Exemplo Host (resposta de rede) Ping IP principal do servidor Interface do Proxmox TCP Port IP, porta 8006 Site ou sistema web HTTP(s) - Keyword URL + palavra que só aparece se a página carregou Servidor Windows/RDP TCP Port IP da VM, porta 3389 Banco de dados TCP Port ou monitor específico MySQL/PostgreSQL/SQL Server com usuário só leitura Container local Docker Container Requer cadastrar o host Docker (socket) Certificado SSL HTTP(s) Ative "Certificate Expiry Notification" - (Opcional) Crie uma Status Page em Status Pages, escolha os monitores que aparecem e, se quiser, aponte um domínio próprio.
Proxy reverso
O Uptime Kuma usa WebSocket. No Nginx, além do proxy_pass http://127.0.0.1:3001;, inclua os cabeçalhos Upgrade e Connection "upgrade" e proxy_http_version 1.1; sem eles o painel fica carregando indefinidamente. O Caddy faz isso automaticamente com reverse_proxy 127.0.0.1:3001.
Como saber se funcionou
- Os monitores aparecem em verde com o tempo de resposta.
- Teste o alerta de verdade: pause um serviço de teste ou crie um monitor TCP para uma porta fechada e confirme que a mensagem chega no Telegram/e-mail, e que chega também a mensagem de recuperação.
Backup e atualização
- Todos os dados ficam em
./data. Faça backup dessa pasta (com o container parado, ou use o recurso de backup do próprio painel quando disponível). - Para atualizar dentro da versão 2.x:
docker compose pull && docker compose up -d. Quem vem da 1.x deve fazer backup antes: a migração para a 2.0 converte o banco e pode demorar com históricos grandes.
Problemas comuns
- Painel não carrega atrás do proxy: faltam os cabeçalhos de WebSocket.
- Monitor de ping falha dentro de LXC: containers não privilegiados podem bloquear ICMP de usuário comum. Use monitor TCP ou rode o Kuma numa VM.
- Alertas falsos às madrugadas: aumente Retries e o intervalo de nova tentativa; verifique se não coincide com a janela de backup das VMs.
- Disco crescendo: reduza a retenção do histórico em Settings → Monitor History.
- WhatsApp: o Kuma tem integrações com gateways como WAHA e Evolution API, que usam APIs não oficiais. Leia os riscos no artigo de alertas antes de usar.
Perguntas frequentes
O Uptime Kuma é gratuito?
Sim. É open source (licença MIT) e auto-hospedado: você só paga pela máquina onde ele roda.
Qual a diferença entre Uptime Kuma e Zabbix?
O Uptime Kuma verifica de fora se sites, portas e serviços respondem. O Zabbix mede por dentro CPU, memória, disco e serviços. Muitos usam os dois juntos. Veja também o artigo «Como instalar Zabbix Agent 2 no Debian, Ubuntu e Proxmox».
Posso instalar o Uptime Kuma no mesmo servidor que ele monitora?
Pode, para vigiar VMs e containers internos, mas se o servidor cair o monitor cai junto e nenhum alerta sai. Tenha sempre uma checagem rodando em outro local.
Como receber alertas do Uptime Kuma no Telegram?
Crie um bot com o @BotFather, pegue o token e o chat ID e cadastre em Settings → Notifications. O passo a passo está no artigo «Como receber alertas do servidor no Telegram, e-mail ou WhatsApp».
Para colocar o painel atrás de HTTPS, veja também os artigos «Como configurar proxy reverso com Nginx ou Caddy: vários sites e VMs em um único IP» e «Como instalar certificado SSL gratuito com Let's Encrypt e Certbot (com renovação automática)».
Leitura complementar
Precisa de ajuda? Abra um ticket ou fale com o suporte pelo WhatsApp.
