Uptime Kuma em um VPS: instalação do monitoramento de sites e servidores

30/08/20267 min de leitura

Tropic

Uptime Kuma em um VPS: instalação do monitoramento de sites e servidores

Uptime Kuma: como instalar seu próprio monitoramento de sites em um VPS

Um site pode apresentar falhas e continuar respondendo com 200 OK. Um backup também pode deixar de ser criado sem mostrar um erro evidente. O Uptime Kuma detecta os dois casos: verifica sites, APIs, portas e tarefas em segundo plano e envia uma notificação quando encontra um problema.

Neste artigo, veremos onde hospedar o monitoramento, qual VPS é necessário e como instalar o Uptime Kuma 2, configurar HTTPS, conectar o Telegram e criar uma página de status.

Uptime Kuma em sete etapas

Separar um pequeno VPS dos projetos que serão monitorados.
Apontar para ele um subdomínio, como monitor.example.com.
Instalar o Docker e iniciar o Uptime Kuma 2.
Fechar a porta interna 3001 para acesso externo e configurar HTTPS.
Criar monitores HTTP, DNS, TCP ou Push.
Configurar o Telegram e, se necessário, uma página de status.
Ativar as atualizações e um backup externo do diretório de dados.

O que é o Uptime Kuma

O Uptime Kuma é uma ferramenta gratuita, de código aberto e auto-hospedada. O painel e o histórico das verificações ficam armazenados no seu próprio servidor.

Ele monitora HTTP(S), portas TCP, ping, DNS, WebSocket, texto e JSON em respostas, sinais Push e contêineres Docker. O intervalo mínimo entre verificações é de 20 segundos. Também oferece dezenas de canais de notificação, 2FA, gráficos de latência, monitoramento de certificados TLS e várias páginas de status.

Como detectar uma falha por trás de um `200 OK`

Uma verificação HTTP comum vê apenas o código de resposta. No entanto, o servidor web pode exibir uma página em branco ou uma tela de erro da aplicação e, mesmo assim, retornar um status de sucesso.

Para um controle mais preciso, use:

Keyword — procura uma frase esperada, como o nome do site ou o texto “Área do cliente”;
JSON Query — verifica um valor na resposta da API, por exemplo status: healthy.

Assim, o monitoramento confirma não apenas que a porta está acessível, mas também um sinal mínimo de que a aplicação está funcionando corretamente.

Monitor Push para backups e tarefas cron

Um monitor Push não consulta o serviço. Em vez disso, ele aguarda um sinal periódico enviado pelo próprio serviço. Um script de backup ou uma tarefa cron acessa uma URL exclusiva após terminar com sucesso. Se o sinal não chegar no prazo, o Uptime Kuma informa a falha.

Isso permite detectar um problema “silencioso”: o site continua funcionando, mas o backup diário não é criado há vários dias.

O que o Uptime Kuma não substitui

O Uptime Kuma monitora principalmente a disponibilidade e o tempo de resposta. Para CPU, RAM, disco, logs e métricas de contêineres, complemente-o com Prometheus, Netdata, Zabbix ou outro sistema: o Kuma identifica o problema por fora, enquanto as métricas ajudam a encontrar a causa.

Por que o monitoramento deve ficar em um VPS separado

Se o Uptime Kuma for instalado junto com o site, uma falha no VPS, na rede ou no data center poderá derrubar tanto o projeto quanto o monitoramento. Nesse caso, a notificação talvez nem seja enviada.

Hospede o painel em um VPS separado e, para projetos importantes, em outra localização ou com outro provedor. Também é útil monitorar o próprio Kuma com um serviço externo: alguém precisa acompanhar o sistema de monitoramento.

Requisitos de servidor do Uptime Kuma

O projeto não define um mínimo oficial rígido de CPU e RAM. Uma configuração inicial prática para uma pequena instalação é:

1 vCPU;
1 GB de RAM;
10 GB de SSD;
Ubuntu 24.04 LTS;
IPv4;
um domínio ou subdomínio para HTTPS.

Essa configuração costuma ser suficiente para algumas dezenas de verificações simples. Para centenas de monitores, um histórico longo ou verificações pelo navegador, escolha 2 GB de RAM ou mais.

Como instalar o Uptime Kuma em um VPS

Neste exemplo, usamos o Ubuntu 24.04 e o subdomínio monitor.example.com.

1. Configure o DNS e o firewall

Crie um registro DNS A apontando para o endereço IPv4 do VPS. Conecte-se por SSH e abra as portas necessárias:

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

Não feche a sessão SSH atual até testar uma nova conexão.

2. Instale o Docker e o Docker Compose

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<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

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker compose version

3. Inicie o Uptime Kuma 2

mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

cat > compose.yaml <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
EOF

docker compose up -d
docker compose ps

Use a tag :2: latest continua apontando para a versão antiga v1. O diretório /app/data deve ficar em um disco local ou em um Docker volume comum. NFS e armazenamentos sem bloqueio correto de arquivos podem corromper o banco de dados.

A porta 3001 fica acessível apenas em 127.0.0.1. Um proxy reverso com HTTPS publicará o painel externamente.

4. Configure HTTPS com o Caddy

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
monitor.example.com {
    reverse_proxy 127.0.0.1:3001
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Se o DNS apontar para o VPS, o Caddy solicitará automaticamente um certificado TLS e encaminhará as conexões WebSocket. Hospede o painel na raiz de um domínio ou subdomínio: um endereço como example.com/kuma não é compatível.

5. Crie a conta de administrador

Abra https://monitor.example.com, crie uma conta com uma senha longa e exclusiva e ative a autenticação de dois fatores.

Como adicionar o primeiro monitor

Clique em Add New Monitor e selecione HTTP(s):

Informe um nome e a URL completa.
Defina um intervalo, por exemplo 60 segundos.
Adicione duas novas tentativas para evitar falsos alertas causados por falhas ocasionais de rede.
Escolha um canal de notificação.
Salve o monitor e confirme que as verificações bem-sucedidas começam a aparecer.

Para o site principal, as verificações HTTP e Keyword são úteis. Para uma API, use um endpoint de saúde e JSON Query. Não exponha bancos de dados nem portas administrativas à internet apenas para monitoramento: use uma rede confiável ou VPN.

Exemplo de monitor Push para backup

Depois de criar um monitor do tipo Push, adicione sua URL exclusiva ao final do script:

backup-command && \
  curl -fsS "https://monitor.example.com/api/push/SECRET_TOKEN?status=up&msg=backup-ok"

A requisição só será executada depois de um backup concluído com sucesso. Trate o token Push como uma senha: qualquer pessoa que conheça a URL poderá enviar um sinal falso.

Como conectar o Telegram

Crie um bot pelo @BotFather, envie uma mensagem para ele e abra Settings → Notifications → Telegram. Informe o Bot Token e o Chat ID, clique em Test e associe o canal aos monitores. Para serviços críticos, adicione um segundo canal, como e-mail.

Como criar uma página de status

Em Status Pages, você pode agrupar monitores, mostrar o estado atual e o histórico de disponibilidade, associar um domínio e informar manutenções programadas por meio de Maintenance. Não publique IPs internos nem URLs técnicas: para os clientes, componentes como “Site”, “API”, “Área do cliente” e “Pagamentos” são suficientes.

Atualização e backup

Antes de uma grande atualização, pare o contêiner e salve o diretório de dados:

cd /opt/uptime-kuma
docker compose down

tar -czf /root/uptime-kuma-$(date +%F).tar.gz \
  data compose.yaml

docker compose up -d

Transfira o arquivo para outro dispositivo ou armazenamento externo. Uma cópia no mesmo VPS não protege contra a exclusão do servidor nem contra uma falha de disco.

Para uma atualização comum:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

Após iniciar, verifique docker compose ps, o painel e uma notificação de teste.

Qual VPS escolher para o Uptime Kuma

Para uma pequena instalação, um VPS Linux com 1 vCPU e 1 GB de RAM é suficiente. A independência é mais importante que o desempenho: o monitor precisa continuar funcionando quando o projeto principal estiver indisponível.

O Uptime Kuma pode ser instalado em um VPS da tropic.host quando os serviços monitorados estão em outra plataforma ou em um nó independente. Ubuntu, Docker e um IP fixo permitem iniciar rapidamente o painel, e os recursos podem ser ampliados conforme o número de verificações aumenta.

Se a produção já estiver na mesma infraestrutura, escolha outro nó ou adicione um monitor externo de reserva. Separar os pontos de falha é mais útil do que adicionar um núcleo de CPU.

Erros comuns

Erro	Por que isso é um problema	Como fazer melhor
O monitoramento fica junto com o projeto	Uma falha comum derruba tanto o serviço quanto as notificações	Usar um VPS ou uma localização separada
A porta `3001` está exposta publicamente	O painel fica acessível sem proxy reverso e HTTPS	Vincular a porta a `127.0.0.1`
Apenas o código `200` é verificado	Uma falha da aplicação pode parecer sucesso	Adicionar Keyword ou JSON Query
A tag `latest` é usada	Ela aponta para a versão antiga v1	Usar `louislam/uptime-kuma:2`
O backup fica no mesmo VPS	Ele desaparecerá junto com o servidor	Copiar o diretório `data` para fora

Resumo

O Uptime Kuma transforma um pequeno VPS em uma central própria de monitoramento para sites, APIs, DNS, portas, certificados e tarefas em segundo plano. Keyword ajuda a detectar uma página quebrada, JSON Query identifica uma resposta incorreta da API e Push revela um backup ou uma tarefa cron que deixou de funcionar.

Para uma configuração confiável, mantenha o monitoramento separado da produção, feche a porta 3001, ative HTTPS e 2FA e configure dois canais de notificação. Em seguida, faça um backup externo do diretório de dados e configure uma verificação independente do próprio Uptime Kuma.

FAQ

O Uptime Kuma é gratuito?

Sim. O projeto é de código aberto e distribuído sob a licença MIT. Você paga apenas pela infraestrutura, pelo domínio e pelos backups externos.

Quanta RAM o Uptime Kuma precisa?

Para uma pequena instalação, 1 GB de RAM é um ponto de partida razoável. Para centenas de verificações, um histórico longo ou o Browser Engine, reserve 2 GB ou mais.

É possível instalar o Uptime Kuma sem Docker?

Sim, usando Node.js e PM2. No entanto, o Docker Compose costuma ser mais fácil de atualizar, migrar e restaurar em um VPS.

É possível usar o Uptime Kuma sem domínio?

Tecnicamente, sim, pelo endereço IP ou por um túnel SSH. Para acesso permanente pela internet, é mais seguro usar um subdomínio com HTTPS.

O Uptime Kuma mostra o uso de CPU, RAM e disco?

Não como um sistema completo de métricas de servidor. Para monitorar os recursos do servidor, complemente-o com Prometheus, Netdata, Zabbix ou outra ferramenta especializada.

Voltar ao Blog