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.
Por Simon Vasconcelos Lee
Publicado em 17 de novembro de 2026Leitura: 12 minutos
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.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.mongodump e guarde seu arquivo .env; depois atualize trocando a tag da imagem: as migrações rodam sozinhas na inicialização.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 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.
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.
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:
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:
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
127.0.0.1: o arquivo de referência a publica sem endereço, e o Docker a abre então em todos os endereços do servidor. Publicada localmente, ela só é acessível pelo proxy reverso.CLIENT_HOST é o endereço que seus usuários digitam, com https://. O Checkmate o usa para as verificações de origem cruzada e para os links de seus alertas e e-mails.NODE_ENV=production: o README pede essa variável nas implantações reais. Sem ela, o aplicativo roda em modo de desenvolvimento, que desativa o limitador de requisições da API.ENCRYPTION_KEY é opcional no arquivo de referência. Ela criptografa os segredos que o Checkmate armazena, e a v4.0.0 a exige para os monitores Docker com TLS e para o Checkmate Connect. Defina-a desde o início: é mais simples do que acrescentá-la depois.latest e a baixa a cada inicialização. Uma versão completa, aqui v4.0.0, permite escolher o momento de cada atualização.mongo-data guarda todos os seus dados: monitores, verificações, usuários e configurações.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:
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.
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.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345: o Checkmate mostra sua página de cadastro.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.
| Papel | O que pode fazer |
|---|---|
| User | Ver todos os monitores, o painel, as verificações, os incidentes, as páginas de status e as configurações, sem alterar nada |
| Admin | Tudo 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 |
| Superadmin | Tudo 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.
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-*.
status.example.com {
reverse_proxy 127.0.0.1:52345
}
sudo systemctl reload caddy
CLIENT_HOST deve conter o mesmo endereço em https:// que o proxy. Depois de alterá-lo, execute docker compose up -d para recriar o contêiner.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”.
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:
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.
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.
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:
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.
Na mesma instalação ou em uma nova, com o mesmo .env, pare o aplicativo, carregue o arquivo e inicie-o de novo:
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.
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:
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump e mongorestore. Nenhuma variável de ambiente nova é exigida.checkmate-client, checkmate-backend e checkmate-mongo, que não são mais atualizadas. Passe para ghcr.io/bluewave-labs/checkmate e mantenha seu serviço MongoDB e o volume dele; as variáveis UPTIME_APP_* não são mais lidas.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.
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.
| Assunto | Nossas equipes | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, com intervenções no servidor incluídas | O momento que convém a sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligação | Seus próprios monitores, alertas e páginas de status no Checkmate |
| Checkmate | Acompanhamento proativo: erros, lentidões, banco de dados e espaço em disco identificados, correção recomendada | A 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 alertas | O servidor que os sustenta, monitorado e com backup | As contas, os papéis, os convites e os canais de notificação |
| Os backups | Toda noite, criptografados e guardados fora da máquina; restauração incluída | As exportações próprias do banco de dados do Checkmate e o pedido de restauração, quando você precisar |
| A migração | Seu servidor atual migrado, grátis | O 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Simafri
Vamos falar de seu site
Conte para a gente sobre seu projeto em poucas palavras: responderemos rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o e-mail? Escreva para a gente em support@simafri.com.