Hospede o Uptime Kuma para status pages e alertas

Você quer saber quando seu site, API ou servidor cai, e quer uma status page para mostrar aos seus clientes sem pagar uma mensalidade por algo que um único container resolve. O Uptime Kuma é uma ferramenta de monitoramento open-source que faz as duas coisas: ele pinga seus endpoints numa agenda, te envia um alerta no momento em que um falha, e te dá uma status page pública para mostrar o resultado. No final disso, você vai ter ele rodando no seu próprio servidor, acessível via HTTPS no seu próprio domínio, com os dados de fato sobrevivendo a um restart.

O que você vai precisar

• Um servidor pequeno. O Uptime Kuma é um único processo Node.js com um banco SQLite, então não precisa de muito, mas dar a ele pelo menos 1 GB de RAM evita os problemas de falta de memória descritos na seção de solução de problemas abaixo. Um Basic Droplet da DigitalOcean com 1 GB de RAM, 1 vCPU e 25 GB de SSD custa US$6/mês até hoje (conferido na própria página de preços da DigitalOcean). A linha econômica da Hetzner é uma alternativa razoável se você preferir comparar.
• Um domínio que você controla, com a capacidade de adicionar um registro A.
• Docker e Docker Compose instalados no servidor (a Etapa 2 cobre isso).
• Alguns minutos na primeira visita para criar a conta de admin. O Uptime Kuma não vem com login padrão nenhum: quem chegar primeiro na página de configuração se torna o admin, então não deixe ela aberta para a internet antes dessa etapa estar feita.

Etapa 1: Aponte seu domínio para o servidor

Crie o servidor primeiro, anote o IP público dele, depois adicione um registro A para o subdomínio que você quer usar, por exemplo status.yourdomain.com, apontando para esse IP. A propagação do DNS geralmente é rápida, mas pode levar até algumas horas dependendo das configurações de TTL do seu registrador.

Você pode conferir se resolveu com:

dig +short status.yourdomain.com

Você deve ver o endereço IP do servidor impresso de volta. Se nada voltar ainda, espere um pouco antes de continuar. Fazer essa etapa primeiro significa que quando você chegar no HTTPS mais tarde, o DNS já teve tempo de se estabilizar.

Etapa 2: Instale o Docker

A própria documentação de instalação do Uptime Kuma recomenda rodar ele como um container, e é essa a configuração que este post usa do início ao fim. Conecte via SSH ao seu servidor e instale o Docker com o script de conveniência oficial:

curl -fsSL https://get.docker.com | sh

O Docker Compose vem como um plugin nas instalações atuais do Docker, então uma etapa de instalação separada geralmente não é necessária. Confirme que os dois estão presentes:

docker --version
docker compose version

Você deve ver um número de versão impresso para cada um. Se docker compose version falhar, sua instalação do Docker é antiga o suficiente para o Compose não vir junto, e você vai precisar instalar o pacote docker-compose-plugin separadamente.

Etapa 3: Escreva o arquivo Compose e inicie o Uptime Kuma

Crie um diretório para o app e um compose.yml dentro dele:

mkdir -p ~/uptime-kuma && cd ~/uptime-kuma

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - uptime-kuma-data:/app/data

volumes:
  uptime-kuma-data:

A tag 1 acompanha a linha de release estável atual e atualiza com releases de patch quando você baixa de novo, em vez de fixar uma build exata. A parte importante é o volume nomeado uptime-kuma-data montado em /app/data: é ali que o Uptime Kuma guarda seu banco SQLite, e é o que faz seus monitores, configurações de notificação e status pages sobreviverem a um restart ou recriação do container. Pule o volume e um docker compose down, ou um reboot do servidor que recria o container, vai apagar todo monitor que você configurou.

Inicie:

docker compose up -d

Confira se está rodando:

docker compose ps

Você deve ver o serviço uptime-kuma listado como running ou healthy. Nesse ponto, ele só é acessível pela porta 3001, o que está tudo bem, já que a Etapa 5 coloca um proxy reverso na frente dele.

Etapa 4: Crie a conta de admin e adicione seu primeiro monitor

Antes de o DNS e o HTTPS estarem no lugar, você ainda pode acessar o app direto pela porta para criar a conta de admin, o que fecha a janela de página de configuração aberta o mais rápido possível:

http://<ip-do-servidor>:3001

A primeira tela pede para você criar um usuário e senha. Não há login padrão para trocar, só uma página em branco. Depois de entrar, adicione um monitor no painel: dê um nome, um tipo (HTTP(s), porta TCP, ping, DNS e outros são suportados), e o alvo para verificar. Defina o intervalo de verificação (60 segundos é um padrão razoável para a maioria dos sites) e salve.

Enquanto estiver lá, vá em Settings → Notifications e adicione pelo menos um canal de notificação (e-mail, Slack, Discord, um webhook genérico, e dezenas de outros são suportados). Use o botão Test na notificação antes de confiar nela: uma URL de webhook mal configurada ou um provedor de e-mail que rejeita a mensagem silenciosamente é a forma mais comum de alguém descobrir, durante uma queda real, que os alertas nunca de fato estavam sendo entregues.

Você deve ver o status do seu novo monitor virar verde (ou vermelho, se você apontou para algo inacessível) dentro de um intervalo de verificação.

Etapa 5: Coloque o Caddy na frente para o HTTPS

Rodar um painel de monitoramento numa porta HTTP simples, sem certificado e sem domínio, é bom para testes, mas não para algo em que você realmente vai confiar. O Caddy é um proxy reverso que solicita e renova um certificado Let’s Encrypt automaticamente, sem configuração separada de certbot.

Instale o Caddy diretamente no servidor (fora do arquivo Compose, para que ele consiga ocupar as portas 80 e 443 de forma limpa):

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Substitua o /etc/caddy/Caddyfile por:

status.yourdomain.com {
	reverse_proxy localhost:3001
}

Recarregue o Caddy para pegar a mudança:

sudo systemctl reload caddy

O Caddy solicita o certificado na primeira vez que vê uma requisição para aquele hostname, o que só funciona se o registro A da Etapa 1 já estiver resolvendo para este servidor. Você deve ver https://status.yourdomain.com carregar o Uptime Kuma com um cadeado válido, e requisições http:// simples para o mesmo hostname devem redirecionar para HTTPS automaticamente. Depois que isso funcionar, bloqueie o acesso direto à porta 3001 no seu firewall para que o app só seja acessível pelo Caddy.

Etapa 6: Faça backup do volume de dados

Tudo que importa (monitores, configurações de notificação, configuração de status page, histórico) vive no arquivo SQLite dentro do volume uptime-kuma-data. Faça backup numa agenda em vez de descobrir que precisa dele durante um incidente real.

Uma abordagem simples e amigável para cron, rodada a partir do host:

docker run --rm \
  -v uptime-kuma_uptime-kuma-data:/data \
  -v ~/uptime-kuma-backups:/backup \
  alpine tar czf /backup/uptime-kuma-$(date +%F).tar.gz -C /data .

Adicione isso como um cron job diário (crontab -e) e mantenha a última semana ou duas de arquivos. Você deve ver um novo arquivo .tar.gz cair em ~/uptime-kuma-backups depois de rodar. Para restaurar, pare o container, extraia o arquivo de volta no mesmo caminho de volume, e inicie de novo.

Etapa 7: Fazendo upgrade depois

Como o arquivo Compose fixa a tag flutuante 1 em vez de uma versão de patch exata, baixar de novo pega a release de patch mais recente dessa linha:

docker compose pull
docker compose up -d

O Docker recria o container com a nova imagem deixando o volume nomeado intacto, então seus dados não são afetados. Confira as release notes na página de releases do Uptime Kuma no GitHub antes de um salto de versão maior especificamente, já que esses podem incluir mudanças que quebram compatibilidade, o que uma release de patch não teria.

O caminho curto: faça com o Railyard

Tudo acima é o caminho manual completo e é uma forma razoável de rodar isso se você quiser ser dono de cada peça dele. Se você preferir pular o provisionamento do servidor, a instalação do Docker, o arquivo Compose e a configuração de proxy reverso e ter o mesmo app rodando, o template de Uptime Kuma do Railyard faz o deploy da mesma imagem com o volume de dados já montado em /app/data e o HTTPS já resolvido. Não há nada para configurar depois do deploy: sem login padrão de qualquer forma, você cria a conta de admin na sua primeira visita, igual ao caminho manual. É o mesmo app, a mesma etapa de configuração, só sem o gerenciamento de servidor no meio.

Se você é novo no Railyard em geral, o quickstart e deploying with a one-click button cobrem o básico, e hosting costs detalha o que um app pequeno como esse costuma custar entre provedores.

Solução de problemas

“Bind for 0.0.0.0:3001 failed: port is already allocated”. Alguma outra coisa no servidor já está usando a porta 3001, geralmente uma tentativa anterior de rodar o container que não foi removida. Confira com docker ps -a e remova o container antigo, ou mude o lado do host no mapeamento de porta em compose.yml (por exemplo, "3002:3001") e atualize o alvo do proxy reverso do Caddy para corresponder.

O Caddy não consegue emitir um certificado. Isso quase sempre é DNS, não o Caddy. Se o registro A da Etapa 1 ainda não propagou, ou aponta para o IP errado, a requisição de validação do Let’s Encrypt nunca chega ao seu servidor e a solicitação de certificado falha silenciosamente nos logs do Caddy (sudo journalctl -u caddy -n 50). Rode o comando dig da Etapa 1 de novo para confirmar que o registro resolve para o IP certo antes de investigar qualquer outra coisa.

Os monitores desapareceram depois de um restart ou redeploy. Isso significa que o container estava rodando sem o volume nomeado, ou com o volume montado no caminho errado. /app/data é o único caminho em que o Uptime Kuma escreve seu banco de dados. Se você rodou um docker run rápido sem -v para testar alguma coisa, os dados daquele container se foram no momento em que ele foi removido. Confira se docker volume ls mostra uptime-kuma_uptime-kuma-data e se é esse que está montado no seu arquivo compose.

As notificações não estão de fato chegando. O Uptime Kuma loga um envio de notificação falho no próprio log de eventos, mas é fácil perder se você não estiver procurando por isso. Sempre use o botão Test em Settings → Notifications logo depois de adicionar um canal, não só quando configurar um monitor pela primeira vez. URLs de webhook levemente erradas, provedores de e-mail que exigem uma senha de app em vez da sua normal, e tokens do Slack que expiraram são as causas mais comuns.

O container fica reiniciando num servidor muito pequeno. Num droplet de 512 MB, o processo Node.js do Uptime Kuma pode ser morto por falta de memória sob carga, especialmente se você adicionar muitos monitores com intervalos de verificação curtos ou ativar monitores que usam um navegador headless. dmesg | grep -i "out of memory" vai confirmar isso. A correção é mais RAM, não mais ajuste fino: um plano de 1 GB é o mínimo realista para operação confortável e sem intervenção.

Perguntas frequentes

O Uptime Kuma é gratuito? Sim, é open source (licença MIT) e self-hosted, então não há assinatura. Você paga só pelo servidor em que ele roda.

Eu preciso de um banco de dados? Não. O Uptime Kuma usa um banco SQLite embutido dentro do próprio volume de dados, então não há nada extra para provisionar ou conectar.

Posso monitorar mais de um site ou servidor a partir de uma única instância? Sim, uma única instância do Uptime Kuma pode rodar qualquer número de monitores, cada um verificado de forma independente na própria agenda e tipo.

A status page é pública por padrão? Status pages são algo que você cria e publica deliberadamente a partir do painel. Monitores individuais não ficam expostos até você adicioná-los a uma status page que você escolhe tornar pública.

Como isso é diferente do UptimeRobot ou Pingdom? Esses são serviços hospedados pelos quais você paga mensalmente e não controla a infraestrutura. O Uptime Kuma te dá o mesmo conjunto essencial de recursos (verificações HTTP/TCP/ping, alertas, status pages públicas) rodando num servidor que é seu, com seu histórico de monitoramento ficando no seu próprio banco de dados em vez do de um fornecedor.

Depois que estiver rodando e com backup, essa é uma das coisas de menor manutenção que você pode self-hospedar: ela fica de olho em tudo mais para você não precisar, e só pede algo de você quando algo de fato está errado.