Hospedar Checkmate em um VPS gerenciado: monitoramento em seu servidor

Hospedar Checkmate em um VPS gerenciado é manter a vigilância de seus sites e servidores em uma máquina própria, que nossas equipes mantêm atualizada e supervisionam dia e noite. O Checkmate é um aplicativo de monitoramento livre e de código aberto sob a licença AGPL-3.0: disponibilidade, tempos de resposta, incidentes, alertas e páginas de status. Este guia segue a imagem Docker oficial dele, na versão v4.0.0, e executamos cada comando em um VPS Simafri antes de escrevê-lo: a instalação com Docker Compose, o HTTPS, a primeira conta, os monitores e os alertas, os backups e as atualizações.

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

Todos os guias

O essencial

  1. A licença AGPL-3.0 permite rodar o Checkmate para você, sua equipe ou seus clientes sem licença a comprar; se você modificá-lo e deixar que outras pessoas o usem pela rede, compartilha suas alterações.
  2. Instale-o com 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 reverso em HTTPS.
  3. Defina JWT_SECRET, ENCRYPTION_KEY e seu endereço público em CLIENT_HOST, e acrescente NODE_ENV=production, que o arquivo de referência deixa de fora.
  4. A primeira pessoa a se cadastrar se torna o Superadmin: crie sua conta logo após a primeira inicialização; depois, todas as outras pessoas entram por convite.
  5. Faça backup do banco de dados MongoDB com mongodump e guarde seu arquivo .env; depois atualize trocando a tag da imagem: as migrações rodam sozinhas na inicialização.

O que o Checkmate faz

O Checkmate verifica seus serviços em intervalos regulares, registra cada resposta e o tempo de resposta dela, e avisa você quando algo para de responder. O desenvolvedor dele, a BlueWave Labs, o descreve como uma ferramenta auto-hospedada 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). Você pode usá-lo gratuitamente, para você, sua empresa ou seus clientes, copiá-lo e modificá-lo.

A cláusula particular dela diz respeito ao uso em rede: se você modificar o Checkmate e deixar que outras pessoas usem sua versão modificada pela rede, deve oferecer a elas o código-fonte dessa versão. Rodar 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 define um mínimo modesto: qualquer VPS Linux com 1 GB de RAM ou mais. Ela acrescenta que o MongoDB usa cerca de 400 MB em uma instância que verifica mais de 300 servidores a cada minuto.

O tamanho do servidor depende, portanto, do número de monitores, do intervalo deles e do histórico que você mantém. Em um VPS gerenciado, conte-nos como você usa o aplicativo e recomendaremos o tamanho certo.

A instalação com 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 roda ao lado, em seu próprio contêiner. Em um servidor com o Docker Engine e o plugin Compose dele, instalados a partir do repositório do Docker para Ubuntu, crie uma pasta como /opt/checkmate e coloque nela este compose.yaml, baseado no arquivo 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 em um arquivo .env ao lado, que o Docker Compose lê sozinho. Crie-o legível apenas pelo root e depois inicie 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

A primeira inicialização executa as migrações do banco de dados; em nosso VPS de teste, o aplicativo ficou saudável em menos de dez segundos. Para verificar se ele 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 que o Superadmin for criado.

A primeira conta, os papéis e os convites

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

Terminal, em seu computador
ssh -L 52345:127.0.0.1:52345 root@status.example.com
  1. Abra http://localhost:52345: o Checkmate mostra sua página de cadastro.
  2. Informe seu nome, sobrenome, endereço de e-mail e uma senha de pelo menos 8 caracteres, com uma letra maiúscula, uma minúscula, um número e um caractere especial.
  3. Cadastre-se: você chega ao painel, conectado como Superadmin.

A partir daí, o cadastro público fica fechado: em nosso VPS de teste, cada novo visitante era enviado para a página de login, e o endereço de cadastro também levava até lá. As outras pessoas entram por convite, pela seção Team das configurações da conta, com o papel User ou Admin. O convite é enviado por e-mail, então precisa das configurações SMTP descritas mais abaixo, e o link dele expira depois de uma hora.

PapelO que pode fazer
UserVer todos os monitores, o painel, as verificações, os incidentes, as páginas de status e as configuraçõ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 status, os convites e as configurações globais, SMTP incluído
SuperadminTudo o que um Admin pode, mais criar contas diretamente, editar outro usuário, alterar um papel ou uma senha

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

HTTPS: o proxy reverso

O contêiner serve o Checkmate em HTTP, na porta 52345. O HTTPS fica a cargo de um proxy reverso colocado na frente: a documentação cita o Caddy, o Traefik e o nginx. Testamos o Caddy, instalado a partir do repositório oficial dele para Debian e Ubuntu: ele obtém sozinho o certificado Let’s Encrypt, renova-o, e repassa por padrã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

Seu primeiro monitor e os alertas dele

  1. Em “Uptime”, clique em “Create monitor” e escolha HTTP/HTTPS.
  2. Informe o endereço a verificar, um nome que você vai reconhecer em um alerta e um intervalo: a documentação recomenda de um a cinco minutos para um serviço crítico.
  3. Salve: o Checkmate executa a primeira verificação na hora. Em nosso VPS de teste, o monitor estava no ar um minuto depois.

O e-mail: as configurações SMTP

Os alertas por e-mail e os convites passam por uma conexão SMTP comum a todo o servidor, definida em “Settings”, aba “Email”: servidor, porta, usuário, senha e endereço do remetente, depois “Save” e “Test”. Em um VPS Simafri, use um servidor SMTP autenticado, na porta 587 ou 465: o serviço de e-mail de seu domínio, ou um serviço de envio. Depois, crie uma notificação por e-mail com os endereços a alertar, e associe-a a seus monitores.

Slack, Discord, Teams, Telegram e os outros canais são criados da mesma forma, em “Notifications”, cada um com seu endereço de webhook ou seu token, e cada um com um botão “Test”.

Monitores heartbeat para suas tarefas agendadas

Um monitor heartbeat vigia uma tarefa que roda sozinha, como um backup noturno. Gere a chave de ping da equipe em “Settings”, aba “Monitoring” (ela só é exibida uma vez), crie um monitor Heartbeat com um slug e uma janela de alerta, depois chame a URL de ping dele 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, à URL marca o monitor como fora do ar na hora, sem esperar a janela passar.

As páginas de status

Em “Status pages”, um Admin publica uma página que lista os monitores escolhidos e a disponibilidade deles, para seus clientes ou sua equipe. Desde a v4.0.0, cada página de status tem um fuso horário, UTC por padrão.

Os backups

Tudo fica em dois lugares: o banco de dados MongoDB, no volume mongo-data, e seu arquivo .env. Guarde este último em lugar seguro: ENCRYPTION_KEY é necessária para ler os segredos armazenados no banco de dados, e JWT_SECRET mantém seus usuários conectados. A imagem do MongoDB inclui o 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

Agende essa cópia e envie-a para fora do servidor; um monitor heartbeat pode avisar você se ela um dia deixar de rodar. Guardados no disco, os arquivos também entram nos backups noturnos do servidor.

A restauração

Na mesma instalação ou em uma nova, com o mesmo .env, pare o aplicativo, carregue o arquivo e inicie-o de novo:

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

Testamos o ciclo completo em nosso VPS: backup, banco de dados de fato apagado, restauração. O monitor e a conta voltaram, e o login funcionou de novo na hora.

O Checkmate v4.0.0 também oferece backups criptografados na nuvem pelo Checkmate Connect, um serviço opcional, gratuito durante o 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 as notas da versão, faça um backup, troque a tag da imagem no compose.yaml, depois baixe a nova imagem e recrie o contêiner. As migrações do banco de dados rodam sozinhas na inicialização:

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 suas URLs nem seus resultados. Ele informa isso no log na inicialização. Para desativá-la, acrescente TELEMETRY_ENABLED=false ao ambiente do serviço checkmate, depois execute docker compose up -d.

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Checkmate continua sendo seu software, com seus monitores e suas configurações.

AssuntoNossas equipesVocê
O servidorAtualizações do sistema e de segurança, com intervenções no servidor incluídasO momento que convém a sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligaçãoSeus próprios monitores, alertas e páginas de status no Checkmate
CheckmateAcompanhamento proativo: erros, lentidões, banco de dados e espaço em disco identificados, correção recomendadaA instalação, as atualizações e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA
Os usuários e os alertasO servidor que os sustenta, monitorado e com backupAs contas, os papéis, os convites e os canais de notificação
Os backupsToda noite, criptografados e guardados fora da máquina; restauração incluídaAs exportações próprias do banco de dados do Checkmate e o pedido de restauração, quando você precisar
A migraçãoSeu servidor atual migrado, grátisO momento da virada

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.

Checkmate, em um servidor cuidado por nós

Com um VPS gerenciado Simafri, nossas equipes mantêm atualizado o servidor de sua instância Checkmate, monitoram-no dia e noite e intervêm sem esperar sua ligação; elas também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica por conta própria ou com seu assistente de IA. Os backups são criptografados todas as noites e guardados fora da máquina, a restauração está incluída, e a migração de seu servidor atual é grátis.

Conhecer os VPS gerenciados

Perguntas frequentes

O Checkmate é gratuito?

Sim. O Checkmate está sob a licença AGPL-3.0: você pode rodá-lo para você, sua equipe ou seus clientes sem licença a comprar. Se você modificá-lo e deixar que outras pessoas o usem pela rede, compartilha suas alterações. Resta o custo do servidor em que ele roda.

Como instalar o Checkmate com 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 em um arquivo .env, defina CLIENT_HOST com 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 na frente um proxy reverso em HTTPS.

Quais são os acessos padrão do Checkmate?

Não há nenhum. A primeira pessoa a se cadastrar em uma instância nova se torna o Superadmin. Crie sua conta logo após a primeira inicialização, por um túnel SSH; depois disso, os visitantes são enviados para a página de login e os novos usuários entram por convite.

Quanta memória o Checkmate exige?

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

Como enviar os alertas do Checkmate por e-mail?

Defina a conexão SMTP em Settings, aba Email: servidor, porta 587 ou 465, usuário, senha e remetente, depois Save e Test. Crie uma notificação por e-mail com os endereços a alertar e associe-a a seus monitores. Os convites usam as mesmas configurações.

Como fazer backup do Checkmate?

Exporte o banco de dados MongoDB com docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, e guarde uma cópia de seu arquivo .env, cuja ENCRYPTION_KEY é necessária para ler os segredos armazenados. Restaure com mongorestore --archive --gzip --drop, com o aplicativo parado.

Como atualizar o Checkmate?

Leia as notas da versão e faça um backup, troque a tag da imagem no compose.yaml, depois execute docker compose pull e docker compose up -d. As migrações do banco de dados rodam sozinhas na inicialização.

Um VPS gerenciado cobre o Checkmate?

Um VPS gerenciado cobre o servidor: sistema, segurança, supervisão e backups. Nossas equipes também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica. Uma intervenção na aplicação é cobrada por hora ou por valor fechado.

Fontes e documentação oficial

Entre em contato