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.
Por Simon Vasconcelos Lee
Publicado a 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 inverso em HTTPS.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.mongodump e guarde o seu ficheiro .env; depois atualize alterando a etiqueta da imagem: as migrações são executadas sozinhas no arranque.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 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.
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.
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:
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:
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 ficheiro de referência publica-a sem endereço, e o Docker abre-a então em todos os endereços do servidor. Publicada localmente, só é acessível através do proxy inverso.CLIENT_HOST é o endereço que os seus utilizadores escrevem, com https://. O Checkmate utiliza-o para as verificações de origem cruzada e para as ligações dos seus alertas e e-mails.NODE_ENV=production: o README pede-o nas implementações reais. Sem ele, a aplicação funciona em modo de desenvolvimento, que desativa o limitador de pedidos da API.ENCRYPTION_KEY é opcional no ficheiro de referência. Cifra os segredos que o Checkmate guarda, e a v4.0.0 exige-a 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 obtém-na em cada arranque. Uma versão completa, aqui v4.0.0, permite-lhe escolher o momento de cada atualização.mongo-data contém todos os seus dados: monitores, verificações, utilizadores e definições.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:
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.
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.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345: o Checkmate mostra a sua página de registo.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ção | O que pode fazer |
|---|---|
| User | Ver todos os monitores, o painel, as verificações, os incidentes, as páginas de estado e as definiçõ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 estado, os convites e as definições globais, SMTP incluído |
| Superadmin | Tudo 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.
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-*.
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 o alterar, execute docker compose up -d para recriar o contentor.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».
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:
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.
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.
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:
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.
Na mesma instalação ou numa nova, com o mesmo .env, pare a aplicação, carregue o arquivo e volte a arrancá-la:
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.
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:
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump e mongorestore. Não é exigida nenhuma variável de ambiente nova.checkmate-client, checkmate-backend e checkmate-mongo, que já não são atualizadas. Passe para ghcr.io/bluewave-labs/checkmate e mantenha o seu serviço MongoDB e o respetivo volume; as variáveis UPTIME_APP_* já não são 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 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.
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.
| Assunto | As nossas equipas | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, intervenções no servidor incluídas | O momento que convém à sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamada | Os seus próprios monitores, alertas e páginas de estado no Checkmate |
| Checkmate | Acompanhamento proativo: erros, lentidão, base de dados e espaço em disco identificados, correção recomendada | A 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 alertas | O servidor que os suporta, vigiado e com cópias de segurança | As contas, as funções, os convites e os canais de notificação |
| As cópias de segurança | Todas as noites, cifradas e guardadas fora da máquina; restauro incluído | As exportações próprias da base de dados do Checkmate e o pedido de restauro, quando precisar |
| A migração | O seu servidor atual migrado, oferecido | O 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Simafri
Vamos falar do seu projeto
Diga-nos em poucas palavras o que precisa: respondemos-lhe rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o email? Escreva-nos para support@simafri.com.