Alojar Checkmate num VPS gerido: a disponibilidade no seu servidor

Alojar Checkmate num VPS gerido é manter a vigilância dos seus sites e servidores numa máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O Checkmate é uma aplicação de monitorização livre e de código aberto sob licença AGPL-3.0: disponibilidade, tempos de resposta, incidentes, alertas e páginas de estado. Este guia segue a sua imagem Docker oficial, na versão v4.0.0, e executámos cada comando num VPS Simafri antes de o escrever: a instalação com o Docker Compose, o HTTPS, a primeira conta, os monitores e os alertas, as cópias de segurança e as atualizações.

Simon Vasconcelos Lee Por Publicado a 17 de novembro de 2026Leitura: 12 minutos

Todos os guias

O essencial

  1. A licença AGPL-3.0 permite-lhe executar o Checkmate para si, para a sua equipa ou para os seus clientes sem licença para comprar; se o modificar e deixar que outros o utilizem através da rede, partilha as suas alterações.
  2. Instale-o com o Docker Compose: a imagem tudo-em-um ghcr.io/bluewave-labs/checkmate e o MongoDB 8.0, com a porta publicada em 127.0.0.1 atrás de um proxy inverso em HTTPS.
  3. Defina JWT_SECRET, ENCRYPTION_KEY e o seu endereço público em CLIENT_HOST, e acrescente NODE_ENV=production, que o ficheiro de referência omite.
  4. A primeira pessoa a registar-se torna-se o Superadmin: crie a sua conta logo após o primeiro arranque; todas as outras pessoas entram depois por convite.
  5. Faça cópia da base de dados MongoDB com mongodump e guarde o seu ficheiro .env; depois atualize alterando a etiqueta da imagem: as migrações são executadas sozinhas no arranque.

O que faz o Checkmate

O Checkmate verifica os seus serviços a intervalos regulares, regista cada resposta e o respetivo tempo de resposta, e avisa-o quando algo deixa de responder. O seu criador, a BlueWave Labs, descreve-o como uma ferramenta autoalojada para acompanhar em tempo real o hardware dos servidores, a disponibilidade, os tempos de resposta e os incidentes.

O que a licença AGPL-3.0 permite

O Checkmate é publicado sob a GNU Affero General Public License, versão 3 (AGPL-3.0). Pode utilizá-lo gratuitamente, para si, para a sua empresa ou para os seus clientes, copiá-lo e modificá-lo.

A sua cláusula particular diz respeito à utilização em rede: se modificar o Checkmate e deixar que outras pessoas utilizem a sua versão modificada através da rede, deve oferecer-lhes o respetivo código-fonte. Executar a imagem oficial sem modificações, como neste guia, não cria essa obrigação. O software é fornecido sem garantia.

Os recursos a prever

A documentação fixa um mínimo modesto: qualquer VPS Linux com 1 GB de RAM ou mais. Acrescenta que o MongoDB utiliza cerca de 400 MB numa instância que verifica mais de 300 servidores a cada minuto.

O tamanho do servidor depende, portanto, do número de monitores, do respetivo intervalo e do histórico que mantém. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

A instalação com o Docker Compose

Desde a versão 3.10, o Checkmate é distribuído como uma única imagem, ghcr.io/bluewave-labs/checkmate, que serve ao mesmo tempo a interface e a API. O MongoDB funciona ao lado, no seu próprio contentor. Num servidor com o Docker Engine e o seu plugin Compose, instalados a partir do repositório do Docker para Ubuntu, crie uma pasta como /opt/checkmate e coloque nela este compose.yaml, baseado no ficheiro de referência do projeto:

compose.yaml
services:
  checkmate:
    image: ghcr.io/bluewave-labs/checkmate:v4.0.0
    restart: always
    ports:
      - "127.0.0.1:52345:52345"
    environment:
      - DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db
      - CLIENT_HOST=https://status.example.com
      - JWT_SECRET=${JWT_SECRET:?set JWT_SECRET in .env}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY:?set ENCRYPTION_KEY in .env}
      - NODE_ENV=production
    stop_grace_period: 60s
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
      interval: 15s
      timeout: 3s
      start_period: 60s
      start_interval: 2s
      retries: 3
    depends_on:
      mongodb:
        condition: service_healthy

  mongodb:
    image: mongo:8.0
    restart: always
    command: ["mongod", "--quiet", "--bind_ip_all"]
    volumes:
      - mongo-data:/data/db
    healthcheck:
      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/27017"]
      interval: 5s
      timeout: 30s
      start_period: 0s
      start_interval: 1s
      retries: 30

volumes:
  mongo-data:

Os dois segredos vão para um ficheiro .env ao lado, que o Docker Compose lê sozinho. Crie-o legível apenas pelo root e depois arranque o conjunto:

Terminal, em /opt/checkmate
umask 077
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -base64 32)" > .env
umask 022
docker compose up -d
docker compose ps

O primeiro arranque executa as migrações da base de dados; no nosso VPS de teste, a aplicação ficou saudável em menos de dez segundos. Para verificar que responde:

Terminal
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:52345/
curl -s http://127.0.0.1:52345/api/v1/auth/users/superadmin

O primeiro comando responde 200. O segundo responde "data":false enquanto não existir nenhuma conta, e true depois de criado o Superadmin.

A primeira conta, as funções e os convites

O Checkmate não tem conta por omissão. A primeira pessoa a registar-se torna-se o Superadmin, por isso crie a sua logo após o primeiro arranque, antes de abrir o endereço ao público. Um túnel SSH traz a porta 52345 do servidor para o seu computador, em http://localhost:52345; acrescente -p e a porta SSH indicada na sua área de cliente.

Terminal, no seu computador
ssh -L 52345:127.0.0.1:52345 root@status.example.com
  1. Abra http://localhost:52345: o Checkmate mostra a sua página de registo.
  2. Introduza o seu nome próprio, o apelido, o endereço de e-mail e uma palavra-passe com pelo menos 8 caracteres, com uma maiúscula, uma minúscula, um algarismo e um carácter especial.
  3. Registe-se: chega ao painel, com sessão iniciada como Superadmin.

A partir daí, o registo público fica fechado: no nosso VPS de teste, cada novo visitante era enviado para a página de início de sessão, e o endereço de registo também levava até lá. As outras pessoas entram por convite, a partir da secção Team das definições da conta, com a função User ou Admin. O convite é enviado por e-mail, por isso precisa das definições SMTP descritas mais abaixo, e a sua ligação expira ao fim de uma hora.

FunçãoO que pode fazer
UserVer todos os monitores, o painel, as verificações, os incidentes, as páginas de estado e as definições, sem alterar nada
AdminTudo o que um User pode, mais os monitores, os canais de notificação, os incidentes, as janelas de manutenção, as páginas de estado, os convites e as definições globais, SMTP incluído
SuperadminTudo o que um Admin pode, mais criar contas diretamente, editar outro utilizador, alterar uma função ou uma palavra-passe

Desde a v4.0.0, as etiquetas, as páginas de estado e os proxies são ações de Admin: um User que antes os podia gerir perde esse acesso após a atualização.

HTTPS: o proxy inverso

O contentor serve o Checkmate em HTTP, na porta 52345. O HTTPS fica a cargo de um proxy inverso colocado à frente: a documentação indica o Caddy, o Traefik e o nginx. Testámos o Caddy, instalado a partir do seu repositório oficial para Debian e Ubuntu: obtém sozinho o certificado Let’s Encrypt, renova-o, e transmite por omissão o cabeçalho Host e os cabeçalhos X-Forwarded-*.

/etc/caddy/Caddyfile
status.example.com {
	reverse_proxy 127.0.0.1:52345
}
Terminal
sudo systemctl reload caddy

O seu primeiro monitor e os respetivos alertas

  1. Em «Uptime», clique em «Create monitor» e escolha HTTP/HTTPS.
  2. Introduza o endereço a verificar, um nome que reconhecerá num alerta e um intervalo: a documentação recomenda de um a cinco minutos para um serviço crítico.
  3. Guarde: o Checkmate executa a primeira verificação de imediato. No nosso VPS de teste, o monitor estava operacional um minuto depois.

O e-mail: as definições SMTP

Os alertas por e-mail e os convites passam por uma ligação SMTP comum a todo o servidor, definida em «Settings», separador «Email»: servidor, porta, utilizador, palavra-passe e endereço do remetente, e depois «Save» e «Test». Num VPS Simafri, utilize um servidor SMTP autenticado, na porta 587 ou 465: o serviço de correio do seu domínio, ou um serviço de envio. Crie depois uma notificação por e-mail com os endereços a alertar, e associe-a aos seus monitores.

O Slack, o Discord, o Teams, o Telegram e os outros canais criam-se da mesma forma, em «Notifications», cada um com o seu endereço de webhook ou o seu token, e cada um com um botão «Test».

Monitores heartbeat para as suas tarefas agendadas

Um monitor heartbeat vigia uma tarefa que é executada sozinha, como uma cópia de segurança noturna. Gere a chave de ping da equipa em «Settings», separador «Monitoring» (só é mostrada uma vez), crie um monitor Heartbeat com um slug e uma janela de alerta, e depois chame o respetivo URL de ping no fim da tarefa:

crontab
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "https://status.example.com/api/v1/heartbeat/<ping-key>/nightly-backup"

Acrescentar /fail, ou o código de saída da tarefa, ao URL marca o monitor como em baixo de imediato, sem esperar que a janela passe.

As páginas de estado

Em «Status pages», um Admin publica uma página que lista os monitores escolhidos e a respetiva disponibilidade, para os seus clientes ou a sua equipa. Desde a v4.0.0, cada página de estado tem um fuso horário, UTC por omissão.

As cópias de segurança

Tudo se encontra em dois sítios: a base de dados MongoDB, no volume mongo-data, e o seu ficheiro .env. Guarde este último em segurança: ENCRYPTION_KEY é necessária para ler os segredos guardados na base de dados, e JWT_SECRET mantém as sessões dos seus utilizadores abertas. A imagem do MongoDB inclui mongodump:

Terminal, em /opt/checkmate
docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db > checkmate-$(date +%F).archive.gz
cp .env env-$(date +%F).bak

Programe esta cópia e envie-a para fora do servidor; um monitor heartbeat pode avisá-lo se alguma vez deixar de ser executada. Guardados no disco, os arquivos entram também nas cópias de segurança noturnas do servidor.

O restauro

Na mesma instalação ou numa nova, com o mesmo .env, pare a aplicação, carregue o arquivo e volte a arrancá-la:

Terminal, em /opt/checkmate
docker compose stop checkmate
docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-11-17.archive.gz
docker compose start checkmate

Testámos o ciclo completo no nosso VPS: cópia, base de dados efetivamente apagada, restauro. O monitor e a conta voltaram, e o início de sessão funcionou de novo de imediato.

O Checkmate v4.0.0 oferece também cópias de segurança cifradas na nuvem através do Checkmate Connect, um serviço opcional, gratuito durante a fase beta, que precisa de ENCRYPTION_KEY e de um Superadmin para inscrever a instalação. As cópias acima funcionam sem ele.

As atualizações

Leia a nota de versão, faça uma cópia de segurança, altere a etiqueta da imagem no compose.yaml, e depois obtenha a nova imagem e recrie o contentor. As migrações da base de dados são executadas sozinhas no arranque:

Terminal, em /opt/checkmate
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration

A telemetria

O Checkmate envia um relatório anónimo por dia: um identificador de instalação, a versão, o modo de instalação e o número de monitores de cada tipo, nunca os seus URL nem os seus resultados. Indica-o no seu registo no arranque. Para a desativar, acrescente TELEMETRY_ENABLED=false ao ambiente do serviço checkmate e depois execute docker compose up -d.

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 Checkmate continua a ser o seu software, com os seus monitores e as suas definições.

AssuntoAs nossas equipasVocê
O servidorAtualizações do sistema e de segurança, intervenções no servidor incluídasO momento que convém à sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamadaOs seus próprios monitores, alertas e páginas de estado no Checkmate
CheckmateAcompanhamento proativo: erros, lentidão, base de dados e espaço em disco identificados, correção recomendadaA sua instalação, as suas atualizações e as suas definições, que aplica diretamente ou com o seu assistente de IA
Os utilizadores e os alertasO servidor que os suporta, vigiado e com cópias de segurançaAs contas, as funções, os convites e os canais de notificação
As cópias de segurançaTodas as noites, cifradas e guardadas fora da máquina; restauro incluídoAs exportações próprias da base de dados do Checkmate e o pedido de restauro, quando precisar
A migraçãoO seu servidor atual migrado, oferecidoO momento da mudança

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.

O Checkmate, num servidor mantido por si

Com um VPS gerido da Simafri, as nossas equipas mantêm atualizado o servidor da sua instância Checkmate, vigiam-no dia e noite e intervêm sem esperar pela sua chamada; acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica diretamente ou com o seu assistente de IA. As cópias de segurança são cifradas todas as noites e guardadas fora da máquina, o seu restauro está incluído, e a migração do seu servidor atual é oferecida.

Descobrir os VPS geridos

Perguntas frequentes

O Checkmate é gratuito?

Sim. O Checkmate está sob licença AGPL-3.0: pode executá-lo para si, para a sua equipa ou para os seus clientes sem licença para comprar. Se o modificar e deixar que outros o utilizem através da rede, partilha as suas alterações. Resta o custo do servidor que o faz funcionar.

Como instalar o Checkmate com o Docker Compose?

Parta do compose.yaml de referência: a imagem ghcr.io/bluewave-labs/checkmate e o MongoDB 8.0. Coloque JWT_SECRET e ENCRYPTION_KEY num ficheiro .env, defina CLIENT_HOST com o seu endereço https e NODE_ENV como production, publique a porta 52345 em 127.0.0.1, execute docker compose up -d e coloque à frente um proxy inverso em HTTPS.

Quais são os acessos por omissão do Checkmate?

Não existem. A primeira pessoa a registar-se numa instância nova torna-se o Superadmin. Crie a sua conta logo após o primeiro arranque, através de um túnel SSH; depois disso, os visitantes são enviados para a página de início de sessão e os novos utilizadores entram por convite.

De quanta memória precisa o Checkmate?

A documentação pede um VPS Linux com 1 GB de RAM ou mais. No nosso VPS de teste, uma instalação nova utilizava cerca de 300 MB para o Checkmate e 280 MB para o MongoDB. O disco cresce com o número de monitores, o respetivo intervalo e o histórico que mantém, 90 dias por omissão.

Como enviar os alertas do Checkmate por e-mail?

Defina a ligação SMTP em Settings, separador Email: servidor, porta 587 ou 465, utilizador, palavra-passe e remetente, e depois Save e Test. Crie uma notificação por e-mail com os endereços a alertar e associe-a aos seus monitores. Os convites utilizam as mesmas definições.

Como fazer cópia de segurança do Checkmate?

Exporte a base de dados MongoDB com docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, e guarde uma cópia do seu ficheiro .env, cuja ENCRYPTION_KEY é necessária para ler os segredos guardados. Restaure com mongorestore --archive --gzip --drop, com a aplicação parada.

Como atualizar o Checkmate?

Leia a nota de versão e faça uma cópia de segurança, altere a etiqueta da imagem no compose.yaml, e depois execute docker compose pull e docker compose up -d. As migrações da base de dados são executadas sozinhas no arranque.

Um VPS gerido cobre o Checkmate?

Um VPS gerido cobre o servidor: sistema, segurança, supervisão e cópias de segurança. As nossas equipas acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica. Uma intervenção na aplicação é faturada à hora ou por pacote.

Fontes e documentação oficial

Guias relacionados

Alojar Uptime Kuma num VPS gerido: vigie os seus serviços em contínuoAlojar Uptime Kuma num VPS gerido é vigiar os seus sites, as suas API e os seus servidores a partir de uma máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O Uptime Kuma é um software livre sob licença MIT. Este guia segue a sua documentação oficial: a instalação com o Docker Compose, o HTTPS, a base de dados, as notificações, as cópias de segurança e as atualizações.Backups de um VPS: o que verificar antes de contratarUma oferta de VPS anuncia quase sempre «cópias de segurança incluídas». Por trás destas palavras pode haver uma cópia todas as noites, guardada fora da máquina e restaurada por especialistas, ou um instantâneo colocado no mesmo disco que o servidor. Este guia dá as perguntas que fazem a diferença, o que cada resposta quer dizer, e a forma de verificar que uma cópia de segurança se restaura.Diferença entre VPS gerido e não gerido: quem faz o quêA diferença entre um VPS gerido e um VPS não gerido resume-se a uma pergunta: quem trata do servidor depois de ele estar a funcionar. No entanto, «gerido» não tem definição oficial e, de um fornecedor de alojamento para outro, a palavra vai da simples instalação do sistema à exploração completa do servidor. Este guia mostra quem faz o quê, linha a linha, com o nível intermédio da assistência, e dá as perguntas que eliminam a ambiguidade antes de assinar.
Contacte-nos