Alojar Uptime Kuma num VPS gerido: vigie os seus serviços em contínuo

O que vigia o Uptime Kuma

O Uptime Kuma consulta os seus serviços a intervalos regulares, até de 20 em 20 segundos, guarda o histórico das respostas e avisa-o assim que um deles deixa de responder. Utiliza-se a partir de uma interface web, disponível em vários idiomas.

• As sondas: HTTP e HTTPS, pesquisa de uma palavra-chave na página, pedido JSON, TCP, WebSocket, ping, registo DNS, contentores Docker, e sonda «push» para uma tarefa agendada que assinala ela própria a sua execução.
• Os alertas: mais de 90 serviços de notificação, entre os quais o Telegram, o Discord, o Slack e o e-mail.
• As páginas de estado: várias páginas públicas, cada uma no seu próprio domínio, se assim o desejar.
• Os certificados: as informações do certificado HTTPS de cada serviço vigiado.
• A conta: autenticação de dois fatores e passagem por um proxy para as sondas que dele precisam.

Coloque o Uptime Kuma noutro servidor que não o dos serviços que vigia. Numa máquina distinta, vê a falha do exterior e envia o alerta enquanto os seus serviços estão parados.

O que permite a licença MIT

O Uptime Kuma é publicado sob a licença MIT. Autoriza a utilizar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender o software, com uma condição: manter a menção de direitos de autor e o texto da licença em qualquer cópia.

Pode, portanto, fazer correr o Uptime Kuma numa empresa, vigiar nele os serviços dos seus clientes e abrir-lhes páginas de estado, sem licença para comprar.

A instalação com o Docker Compose

A documentação do Uptime Kuma começa pelo Docker Compose. Num servidor com o Docker instalado, crie uma pasta e obtenha o ficheiro oficial:

mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml

O ficheiro do projeto publica a porta 3001 em todos os endereços do servidor. Atrás de um proxy inverso, limite-a ao endereço local, como propõe o README:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"

docker compose up -d

• Uma porta publicada em 127.0.0.1: o Docker publica por predefinição em todos os endereços do servidor, antes das regras da firewall ufw. Em local, o Uptime Kuma só é acessível através do proxy inverso.
• Uma pasta data num disco local: guarda a base kuma.db, os ficheiros enviados e as capturas de ecrã. O projeto afasta o NFS e os outros sistemas de ficheiros em rede, porque o SQLite precisa de bloqueios de ficheiros fiáveis.
• A etiqueta 2 acompanha a versão 2 do Uptime Kuma, e a passagem a uma versão principal seguinte continua a ser uma escolha sua.
• A imagem 2-slim é mais leve, cerca de 185 MB a transferir contra 620 MB: dispensa o Chromium e o MariaDB integrado que a imagem 2 inclui. A imagem 2 é a que o projeto recomenda, e uma sonda «Browser Engine» pede então um Chromium externo com a 2-slim.

No primeiro arranque, abra a interface: um assistente leva-o a escolher a base de dados e depois a criar a conta de administrador. Ative a autenticação de dois fatores logo no primeiro início de sessão.

O projeto não quantifica nem a memória nem o processador: o tamanho depende do número de serviços a vigiar e da frequência pretendida. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

HTTPS e WebSocket: o proxy inverso

Numa rede pública, o projeto pede HTTPS. O Uptime Kuma assenta no WebSocket: o proxy inverso tem de transmitir os cabeçalhos Upgrade e Connection. Serve-se na raiz de um domínio ou de um subdomínio, e o seu wiki afasta as subpastas como example.com/uptimekuma.

Com o Caddy

O Caddy obtém e renova sozinho o certificado, e transmite o WebSocket sem mais nenhuma definição:

uptime.example.com {
    reverse_proxy 127.0.0.1:3001
}

Com o Nginx e o Certbot

server {
    listen 80;
    server_name uptime.example.com;

    location / {
        proxy_pass         http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
    }
}

O Certbot instala depois o certificado Let’s Encrypt e o redirecionamento para HTTPS, e renova o certificado por si próprio:

sudo certbot --nginx -d uptime.example.com

Quando o Uptime Kuma só é acessível pelo proxy, abra as suas definições, «Settings», «Reverse Proxy», «HTTP Headers», e passe «Trust Proxy» a «Yes»: os registos passam então a mostrar o endereço real dos visitantes.

SQLite ou MariaDB

Desde a versão 2, o Uptime Kuma propõe três bases de dados, à escolha no assistente do primeiro arranque:

Para fixar a escolha antecipadamente, sem passar pelo assistente, as variáveis UPTIME_KUMA_DB_TYPE, UPTIME_KUMA_DB_HOSTNAME, UPTIME_KUMA_DB_PORT, UPTIME_KUMA_DB_NAME, UPTIME_KUMA_DB_USERNAME e UPTIME_KUMA_DB_PASSWORD acrescentam-se ao serviço no compose.yaml.

As notificações, e-mail incluído

Uma sonda só serve se o alerta lhe chegar. Declare os seus canais em «Settings», «Notifications», envie uma mensagem de teste a partir de cada um e preveja dois, por exemplo uma aplicação de mensagens e o e-mail: se um falhar, o outro assume.

Para o e-mail, o Uptime Kuma liga-se a um servidor SMTP. Num VPS Simafri, o envio passa por uma retransmissão autenticada, na porta 587: o endereço de uma conta de correio que já tenha, ou o Simafri Suite.

Cópias de segurança e atualizações

Desde a versão 2, a cópia da pasta data é o único método que o projeto suporta. Com o SQLite ou o MariaDB integrado, tudo lá cabe. Uma base SQLite copiada em plena escrita pode ficar corrompida: pare o contentor durante a cópia, sabendo que as sondas param com ele.

docker compose stop
tar -czf uptime-kuma-$(date +%F).tar.gz data
docker compose start

Atualizar

O wiki do projeto dá dois comandos, a partir da pasta do compose.yaml. A pasta data mantém-se no lugar:

docker compose pull
docker compose up -d --force-recreate

Leia as notas de versão antes de cada atualização: algumas trazem correções de segurança, como a 2.5.9, de 31 de outubro de 2026. Uma cópia de segurança logo antes dá-lhe um regresso simples ao estado anterior.

A passagem da versão 1 à versão 2 pede mais cuidado: faça uma cópia da pasta data, com o contentor parado, e deixe a migração chegar ao fim, porque uma migração interrompida obriga a restaurar a cópia. O projeto registou cerca de 7 minutos para 20 sondas e 90 dias de histórico, e muito mais numa máquina modesta ou com mais sondas.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Uptime Kuma continua a ser o seu software, com as suas definições e os seus dados.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.