Uptime Kuma na VPS: como monitorar se o site caiu

Aprenda a instalar o Uptime Kuma com Docker, criar monitores, receber avisos quando o site parar de responder e abrir o painel por domínio com Nginx.

Por Redação Eleven Host · @robson.direitodigital · 31 de outubro de 2026 · 9 min de leitura

O Uptime Kuma é um monitor que você instala no seu próprio servidor e que avisa quando um site ou serviço para de responder. Ele checa o endereço de tempos em tempos e mostra o resultado numa tela web.

Este guia mostra o que o Uptime Kuma monitora, como instalá-lo com Docker numa VPS (veja o guia de servidor VPS para iniciantes), como criar o primeiro monitor, receber avisos, publicar uma página de status, abrir o painel por domínio com Nginx e atualizar a ferramenta. Na página de lançamentos do projeto, a versão marcada como mais recente é a 2.5.8, de 26 de outubro, e os comandos oficiais usam a série 2, que é a que o guia segue. Os endereços dos exemplos são fictícios.

Para que serve e o que ele monitora

O README do projeto o descreve como uma ferramenta de monitoramento fácil de usar, que você hospeda por conta própria. Em vez de depender de um serviço de terceiros, você roda o monitor na sua máquina e guarda os dados nela.

Os tipos de monitor que o README lista são estes:

• Site (HTTP/HTTPS): checa se o endereço responde.
• Porta TCP: checa se uma porta aceita conexão.
• Palavra-chave na página (Keyword): procura um texto na resposta do site.
• Consulta em JSON (Json Query): lê um campo da resposta em JSON.
• WebSocket: checa um serviço que usa esse protocolo.
• Ping: envia um pedido de eco ao endereço.
• Registro DNS: consulta um registro de DNS.
• Push: o próprio serviço é que avisa o Kuma de que está vivo.
• Servidor de jogo Steam e contêineres Docker: também estão na lista.

O README cita ainda checagens a cada 20 segundos entre os recursos, além de informações de certificado, suporte a proxy, autenticação em dois fatores e vários idiomas na interface.

Antes de começar

Para seguir a instalação deste guia você precisa de um servidor Linux com o Docker instalado e acesso ao terminal. A wiki de instalação do projeto lista as principais distribuições Linux (Debian, Ubuntu, CentOS, Fedora e Arch Linux) e o Windows 10 x64. Sem Docker, a instalação exige Node.js 20.4 ou mais novo, mas esse caminho não é o deste guia.

Uma dica nossa, que não vem da documentação do projeto: quando for possível, rode o monitor em uma máquina diferente da que você quer vigiar. Se o Uptime Kuma estiver na mesma VPS do seu site e essa VPS inteira parar, o monitor para junto e não tem como avisar você.

Instalar com Docker

O comando oficial do README sobe o Uptime Kuma em um contêiner:

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

O que cada parte faz:

• -p 3001:3001: a porta 3001 do servidor leva à porta 3001 do contêiner, que é a do painel.
• -v uptime-kuma:/app/data: cria o volume uptime-kuma e o monta em /app/data, onde ficam os dados.
• --restart=always: define a política de reinício do contêiner. A wiki de instalação mostra o mesmo comando com --restart=unless-stopped.
• louislam/uptime-kuma:2: a imagem, na série 2.

Segundo o README, o Uptime Kuma passa a rodar em todas as interfaces de rede da máquina, e o painel abre em http://203.0.113.10:3001 (troque pelo endereço do seu servidor) ou em http://localhost:3001 se você estiver na própria máquina.

Aviso sobre o disco

O README avisa que sistemas de arquivos como NFS não são suportados: mapeie para uma pasta local ou um volume. A wiki explica o motivo, que é a necessidade de travas de arquivo POSIX para evitar corrupção do banco SQLite.

Alternativa com Docker Compose

O README também manda baixar o arquivo compose.yaml oficial e rodar docker compose up -d. O conteúdo do arquivo é este:

services:

  uptime-kuma:

    image: louislam/uptime-kuma:2

    restart: unless-stopped

    volumes:

      - ./data:/app/data

    ports:

      - "3001:3001"

Aqui os dados ficam na pasta ./data, ao lado do arquivo. Se você ainda não usou o Compose, o guia Docker Compose: como usar na VPS, passo a passo explica o formato do arquivo e os comandos básicos.

Primeiro acesso e conta de administrador

Com o contêiner no ar, abra o endereço da porta 3001 no navegador. A primeira tela traz o texto "Create your admin account", que pede a criação da conta de administrador. Na série 2, a interface também pergunta qual banco de dados usar, e as opções documentadas na wiki de variáveis de ambiente são sqlite e mariadb.

Guarde bem o usuário e a senha que você escolher aqui: é por eles que você entra no painel nas próximas vezes.

Criar o primeiro monitor

Depois de entrar, crie um monitor para o seu site. Os nomes dos campos na interface, em inglês, são estes:

• Monitor Type: o tipo de monitor, entre os da lista acima.
• Friendly Name: o nome que aparece no painel.
• Heartbeat Interval: o intervalo entre as checagens.
• Retries: quantas tentativas o Kuma faz antes de marcar o serviço como fora do ar.
• Heartbeat Retry Interval: o intervalo entre essas novas tentativas.
• Resend Notification if Down X times consecutively: repete o aviso enquanto o serviço continua fora.
• Upside Down Mode: inverte a lógica, e o serviço "no ar" vira um alerta.
• Certificate Expiry Notification: avisa quando o certificado está perto de vencer.
• Maintenance: define uma janela de manutenção.

Escolha os valores de intervalo e de tentativas conforme o que você precisa vigiar. Quanto menor o intervalo, mais cedo a queda aparece, e o README confirma que checagens a cada 20 segundos são possíveis.

Quer conhecer a VPS da Eleven Host? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer a VPS

Receber avisos de queda

De nada adianta o monitor perceber a queda se ninguém fica sabendo. O README lista notificações por Telegram, Discord, Gotify, Slack, Pushover e e-mail (SMTP), além de mais de 90 serviços de notificação no total. Escolha o canal que você já olha no dia a dia, como o Telegram, o Discord ou o e-mail.

O campo Resend Notification if Down X times consecutively, visto na seção anterior, controla a repetição do aviso enquanto o serviço seguir fora do ar.

Página de status

O README cita o recurso de várias páginas de status e a possibilidade de ligar cada uma delas a um domínio específico. É um jeito de mostrar a quem usa seu serviço se ele está respondendo.

Acessar o painel por domínio com Nginx

Se você quer abrir o painel em um endereço como status.example.com em vez de IP:3001, o caminho é um proxy reverso. O README mostra como expor o Uptime Kuma só na própria máquina, trocando a porta do comando por 127.0.0.1:3001:3001:

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

A wiki de proxy reverso do projeto faz um alerta: ao contrário de outras aplicações web, o Uptime Kuma é baseado em WebSocket. O proxy precisa dos cabeçalhos Upgrade e Connection para aceitar esse protocolo. O exemplo oficial com SSL, com o domínio e os caminhos trocados por fictícios, é este:

server {

  listen 443 ssl http2;

  server_name status.example.com;

  ssl_certificate /caminho/do/certificado.crt;

  ssl_certificate_key /caminho/da/chave.key;

  location / {

    proxy_set_header X-Real-IP $remote_addr;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_set_header Host $host;

    proxy_pass http://localhost:3001/;

    proxy_http_version 1.1;

    proxy_set_header Upgrade $http_upgrade;

    proxy_set_header Connection "upgrade";

  }

}

Confira o nome e o caminho dos arquivos de certificado na sua máquina antes de usar as duas linhas ssl_certificate. Se o seu domínio passa pela Cloudflare, a wiki também manda ativar a opção "WebSockets" no painel dela.

Para instalar o Nginx do zero, siga o guia Instalar Nginx no Ubuntu: passo a passo na VPS. Para mandar quem digita o endereço sem HTTPS para a versão segura, veja Redirecionar HTTP para HTTPS: passo a passo no Nginx.

Atualizar o Uptime Kuma

Na instalação com Docker, a wiki de atualização manda baixar a imagem de novo e criar outro contêiner com o mesmo volume:

docker pull louislam/uptime-kuma:2

docker stop uptime-kuma

docker rm uptime-kuma

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

O docker rm apaga só o contêiner. Os dados continuam no volume uptime-kuma, e o contêiner novo usa o mesmo volume. Quem instalou com Compose, na pasta do arquivo, roda:

docker compose pull

docker compose up -d --force-recreate

Uma dica nossa, e não da documentação: antes de atualizar, copie os dados para outro lugar. A página de atualização não fala de cópia de segurança.

Se você vem da versão 1.x, o guia de migração da wiki pede uma cópia da pasta data, avisa que a migração do banco pode levar de minutos a horas em máquinas mais lentas ou com muitos monitores e manda não interromper o processo.

Quer ver os planos de VPS da Eleven Host? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver planos de VPS

Perguntas frequentes

O que é o Uptime Kuma?

É uma ferramenta de monitoramento que você instala no seu servidor. Ela checa sites e serviços e avisa quando algum deles para de responder.

Qual comando instala o Uptime Kuma com Docker?

O comando oficial do README é docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2. O painel abre na porta 3001.

Para onde o Uptime Kuma pode mandar avisos?

O README cita Telegram, Discord, Gotify, Slack, Pushover e e-mail (SMTP), além de mais de 90 serviços de notificação.

Perco meus monitores ao atualizar?

Na atualização oficial com Docker, o contêiner é recriado com o mesmo volume, então os dados guardados em /app/data continuam lá.