Ospitare Checkmate su un VPS gestito significa tenere la sorveglianza dei vostri siti e dei vostri server su una macchina tutta vostra, che i nostri team tengono aggiornata e supervisionano giorno e notte. Checkmate è un'applicazione libera di monitoraggio con licenza AGPL-3.0: disponibilità, tempi di risposta, incidenti, avvisi e pagine di stato. Questa guida segue la sua immagine Docker ufficiale alla versione v4.0.0, e abbiamo eseguito ogni comando su un VPS Simafri prima di scriverla: l'installazione con Docker Compose, HTTPS, il primo account, i monitor e gli avvisi, i backup e gli aggiornamenti.
Di Simon Vasconcelos Lee
Pubblicato il 17 novembre 2026Lettura: 12 minuti
ghcr.io/bluewave-labs/checkmate e MongoDB 8.0, con la porta pubblicata su 127.0.0.1 dietro un reverse proxy in HTTPS.JWT_SECRET, ENCRYPTION_KEY e il vostro indirizzo pubblico in CLIENT_HOST, e aggiungete NODE_ENV=production, che il file di riferimento omette.mongodump e conservate il vostro file .env, poi aggiornate cambiando il tag dell'immagine: le migrazioni partono da sole all'avvio.Checkmate controlla i vostri servizi a intervalli regolari, registra ogni risposta e il suo tempo di risposta, e vi avvisa quando qualcosa smette di rispondere. Il suo sviluppatore, BlueWave Labs, lo descrive come uno strumento self-hosted per seguire in tempo reale l'hardware dei server, la disponibilità, i tempi di risposta e gli incidenti.
Checkmate è pubblicato con la GNU Affero General Public License, versione 3 (AGPL-3.0). Potete usarlo gratuitamente, per voi, per la vostra azienda o per i vostri clienti, copiarlo e modificarlo.
La sua clausola particolare riguarda l'uso in rete: se modificate Checkmate e fate usare ad altre persone la vostra versione modificata via rete, dovete offrire loro il suo codice sorgente. Far girare l'immagine ufficiale senza modifiche, come in questa guida, non crea alcun obbligo di questo tipo. Il software è fornito senza garanzia.
La documentazione fissa una soglia modesta: qualsiasi VPS Linux con almeno 1 GB di RAM. Aggiunge che MongoDB usa circa 400 MB su un'istanza che controlla più di 300 server ogni minuto.
La dimensione del server dipende quindi dal numero di monitor, dal loro intervallo e dalla cronologia che conservate. Su un VPS gestito, descriveteci il vostro utilizzo e vi consiglieremo la dimensione giusta.
Dalla versione 3.10, Checkmate è distribuito come un'unica immagine, ghcr.io/bluewave-labs/checkmate, che serve sia l'interfaccia sia l'API. MongoDB gira accanto, nel suo container. Su un server con Docker Engine e il suo plugin Compose, installati dal repository di Docker per Ubuntu, create una cartella come /opt/checkmate e metteteci questo compose.yaml, basato sul file di riferimento del progetto:
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:
I due segreti vanno in un file .env accanto, che Docker Compose legge da solo. Createlo leggibile solo da root, poi avviate lo stack:
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: il file di riferimento la pubblica senza indirizzo, e Docker la apre allora su tutti gli indirizzi del server. Pubblicata in locale, è raggiungibile solo attraverso il reverse proxy.CLIENT_HOST è l'indirizzo che digitano i vostri utenti, con https://. Checkmate lo usa per i controlli cross-origin e per i link nei suoi avvisi e nelle sue e-mail.NODE_ENV=production: il README lo richiede nei deployment reali. Senza, l'applicazione gira in modalità sviluppo, che disattiva il rate limiter dell'API.ENCRYPTION_KEY è facoltativa nel file di riferimento. Cifra i segreti che Checkmate memorizza, e la v4.0.0 la richiede per i monitor Docker in TLS e per Checkmate Connect. Impostatela fin dall'inizio: è più semplice che aggiungerla dopo.latest e lo scarica a ogni avvio. Una versione completa, qui v4.0.0, vi lascia scegliere il momento di ogni aggiornamento.mongo-data contiene tutti i vostri dati: monitor, controlli, utenti e impostazioni.Il primo avvio esegue le migrazioni del database; sul nostro VPS di test, l'applicazione risultava in salute in meno di dieci secondi. Per verificare che risponda:
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
Il primo comando risponde 200. Il secondo risponde "data":false finché non esiste alcun account, e true una volta creato il Superadmin.
Checkmate non ha alcun account predefinito. La prima persona che si registra diventa Superadmin: create quindi il vostro subito dopo il primo avvio, prima di aprire l'indirizzo al pubblico. Un tunnel SSH porta la porta 52345 del server sul vostro computer, su http://localhost:52345; aggiungete -p e la porta SSH indicata nella vostra area clienti.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345: Checkmate mostra la sua pagina di registrazione.Da quel momento la registrazione pubblica è chiusa: sul nostro VPS di test, ogni nuovo visitatore veniva rimandato alla pagina di accesso, e anche l'indirizzo di registrazione portava lì. Le altre persone entrano su invito, dalla sezione Team delle impostazioni dell'account, con il ruolo User o Admin. L'invito parte via e-mail, quindi richiede le impostazioni SMTP descritte più avanti, e il suo link scade dopo un'ora.
| Ruolo | Cosa può fare |
|---|---|
| User | Vedere tutti i monitor, la dashboard, i controlli, gli incidenti, le pagine di stato e le impostazioni, senza modificare nulla |
| Admin | Tutto ciò che può fare un User, più i monitor, i canali di notifica, gli incidenti, le finestre di manutenzione, le pagine di stato, gli inviti e le impostazioni globali, SMTP compreso |
| Superadmin | Tutto ciò che può fare un Admin, più la creazione diretta di account, la modifica di un altro utente, il cambio di un ruolo o di una password |
Dalla v4.0.0, tag, pagine di stato e proxy sono azioni riservate agli Admin: uno User che prima poteva gestirli perde quell'accesso dopo l'aggiornamento.
Il container serve Checkmate in HTTP, sulla porta 52345. HTTPS è affidato a un reverse proxy posto davanti: la documentazione cita Caddy, Traefik e nginx. Abbiamo testato Caddy, installato dal suo repository ufficiale per Debian e Ubuntu: ottiene da solo il certificato Let's Encrypt, lo rinnova, e inoltra per impostazione predefinita l'intestazione Host e le intestazioni X-Forwarded-*.
status.example.com {
reverse_proxy 127.0.0.1:52345
}
sudo systemctl reload caddy
CLIENT_HOST deve contenere lo stesso indirizzo https:// del proxy. Dopo averlo cambiato, eseguite docker compose up -d per ricreare il container.Gli avvisi via e-mail e gli inviti passano da una connessione SMTP valida per tutto il server, impostata in «Settings», scheda «Email»: host, porta, utente, password e indirizzo del mittente, poi «Save» e «Test». Su un VPS Simafri, usate un server SMTP autenticato, sulla porta 587 o 465: il servizio di posta del vostro dominio, o un servizio di invio. Create poi una notifica e-mail con gli indirizzi da avvisare, e collegatela ai vostri monitor.
Slack, Discord, Teams, Telegram e gli altri canali si creano allo stesso modo, in «Notifications», ciascuno con il suo indirizzo di webhook o il suo token, e ciascuno con un pulsante «Test».
Un monitor Heartbeat sorveglia un job che gira da solo, come un backup notturno. Generate la chiave di ping del team in «Settings», scheda «Monitoring» (viene mostrata una sola volta), create un monitor Heartbeat con uno slug e una finestra di avviso, poi chiamate il suo URL di ping alla fine del job:
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "https://status.example.com/api/v1/heartbeat/<ping-key>/nightly-backup"
Aggiungere /fail, o il codice di uscita del job, all'URL segna subito il monitor come down, senza aspettare che la finestra scada.
In «Status pages», un Admin pubblica una pagina che elenca i monitor scelti e la loro disponibilità, per i vostri clienti o per il vostro team. Dalla v4.0.0, ogni pagina di stato ha un fuso orario, UTC per impostazione predefinita.
Tutto si trova in due posti: il database MongoDB, nel volume mongo-data, e il vostro file .env. Conservate quest'ultimo al sicuro: ENCRYPTION_KEY serve a leggere i segreti memorizzati nel database, e JWT_SECRET mantiene connessi i vostri utenti. L'immagine di MongoDB include mongodump:
docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db > checkmate-$(date +%F).archive.gz
cp .env env-$(date +%F).bak
Pianificate questa copia e inviatela fuori dal server; un monitor Heartbeat può avvisarvi se un giorno smette di girare. Conservati sul disco, gli archivi rientrano anche nei backup notturni del server.
Sulla stessa installazione o su una nuova, con lo stesso .env, fermate l'applicazione, caricate l'archivio, poi riavviatela:
docker compose stop checkmate
docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-11-17.archive.gz
docker compose start checkmate
Abbiamo testato l'intero ciclo sul nostro VPS: backup, database effettivamente cancellato, ripristino. Il monitor e l'account sono tornati, e l'accesso ha funzionato di nuovo subito.
Checkmate v4.0.0 offre anche backup cifrati nel cloud tramite Checkmate Connect, un servizio facoltativo, gratuito durante la sua beta, che richiede ENCRYPTION_KEY e un Superadmin per registrare l'installazione. Le copie descritte sopra funzionano senza.
Leggete le note di rilascio, fate un backup, cambiate il tag dell'immagine nel compose.yaml, poi scaricate la nuova immagine e ricreate il container. Le migrazioni del database partono da sole all'avvio:
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump e mongorestore. Non è richiesta alcuna nuova variabile d'ambiente.checkmate-client, checkmate-backend e checkmate-mongo, che non sono più aggiornate. Passate a ghcr.io/bluewave-labs/checkmate conservando il vostro servizio MongoDB e il suo volume; le variabili UPTIME_APP_* non vengono più lette.Checkmate invia un rapporto anonimo al giorno: un ID di installazione, la versione, il metodo di installazione e il numero di monitor di ogni tipo, mai i vostri URL o i vostri risultati. Lo dichiara nel suo log all'avvio. Per disattivarla, aggiungete TELEMETRY_ENABLED=false all'ambiente del servizio checkmate, poi eseguite docker compose up -d.
Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; Checkmate resta il vostro software, con i suoi monitor e le vostre impostazioni.
| Argomento | I nostri team | Voi |
|---|---|---|
| Il server | Aggiornamenti del sistema e della sicurezza, interventi sul server compresi | Il momento più adatto alla vostra attività |
| La supervisione | Server seguito 24 ore su 24, 7 giorni su 7, con intervento senza attendere la vostra chiamata | I vostri monitor, avvisi e pagine di stato in Checkmate |
| Checkmate | Monitoraggio proattivo: errori, rallentamenti, database e spazio su disco individuati, correzione raccomandata | La sua installazione, i suoi aggiornamenti e le sue impostazioni, che applicate voi o il vostro assistente IA |
| Gli utenti e gli avvisi | Il server che li ospita, sorvegliato e salvato | Gli account, i ruoli, gli inviti e i canali di notifica |
| I backup | Ogni notte, cifrati e conservati fuori dalla macchina; ripristino compreso | Le esportazioni del database proprie di Checkmate e la richiesta di ripristino, quando ne avete bisogno |
| La migrazione | Il vostro server attuale migrato, in omaggio | Il momento del passaggio |
Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.
Con un VPS gestito Simafri, i nostri team tengono aggiornato il server della vostra istanza Checkmate, lo sorvegliano giorno e notte e intervengono senza attendere la vostra chiamata; seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi o il vostro assistente IA. I backup sono cifrati ogni notte e conservati fuori dalla macchina, il loro ripristino è compreso e la migrazione del vostro server attuale è in omaggio.
Sì. Checkmate ha licenza AGPL-3.0: potete farlo girare per voi, per il vostro team o per i vostri clienti senza alcuna licenza da acquistare. Se lo modificate e lo fate usare ad altri via rete, condividete le vostre modifiche. Resta il costo del server che lo fa girare.
Partite dal compose.yaml di riferimento: l'immagine ghcr.io/bluewave-labs/checkmate e MongoDB 8.0. Mettete JWT_SECRET ed ENCRYPTION_KEY in un file .env, impostate CLIENT_HOST sul vostro indirizzo https e NODE_ENV su production, pubblicate la porta 52345 su 127.0.0.1, eseguite docker compose up -d e mettete davanti un reverse proxy in HTTPS.
Non ce ne sono. La prima persona che si registra su una nuova istanza diventa Superadmin. Create il vostro account subito dopo il primo avvio, tramite un tunnel SSH; in seguito, i visitatori vengono rimandati alla pagina di accesso e i nuovi utenti entrano su invito.
La documentazione chiede un VPS Linux con almeno 1 GB di RAM. Sul nostro VPS di test, una nuova installazione usava circa 300 MB per Checkmate e 280 MB per MongoDB. Il disco cresce con il numero di monitor, il loro intervallo e la cronologia che conservate, 90 giorni per impostazione predefinita.
Impostate la connessione SMTP in Settings, scheda Email: host, porta 587 o 465, utente, password e mittente, poi Save e Test. Create una notifica e-mail con gli indirizzi da avvisare e collegatela ai vostri monitor. Gli inviti usano le stesse impostazioni.
Esportate il database MongoDB con docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, e conservate una copia del vostro file .env, la cui ENCRYPTION_KEY serve a leggere i segreti memorizzati. Ripristinate con mongorestore --archive --gzip --drop, con l'applicazione ferma.
Leggete le note di rilascio e fate un backup, cambiate il tag dell'immagine in compose.yaml, poi eseguite docker compose pull e docker compose up -d. Le migrazioni del database partono da sole all'avvio.
Un VPS gestito copre il server: sistema, sicurezza, supervisione e backup. I nostri team seguono anche la vostra istanza in modo proattivo e vi raccomandano le correzioni utili, che applicate voi. Un intervento nell'applicazione si fattura a ore o a forfait.
Simafri
Parliamo del vostro progetto
Diteci in due parole ciò che vi serve: vi rispondiamo rapidamente.
Grazie! La tua richiesta è stata inviata. Ti risponderemo a breve.
Preferite l'email? Scriveteci a support@simafri.com.