Ospitare Checkmate su un VPS gestito: il monitoraggio, sul vostro server

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.

Simon Vasconcelos Lee Di Pubblicato il 17 novembre 2026Lettura: 12 minuti

Tutte le guide

In breve

  1. La licenza AGPL-3.0 permette di far girare Checkmate 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.
  2. Installatelo con Docker Compose: l'immagine tutto in uno ghcr.io/bluewave-labs/checkmate e MongoDB 8.0, con la porta pubblicata su 127.0.0.1 dietro un reverse proxy in HTTPS.
  3. Impostate JWT_SECRET, ENCRYPTION_KEY e il vostro indirizzo pubblico in CLIENT_HOST, e aggiungete NODE_ENV=production, che il file di riferimento omette.
  4. La prima persona che si registra diventa Superadmin: create il vostro account subito dopo il primo avvio, poi tutti gli altri entrano su invito.
  5. Salvate il database MongoDB con mongodump e conservate il vostro file .env, poi aggiornate cambiando il tag dell'immagine: le migrazioni partono da sole all'avvio.

Cosa fa Checkmate

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.

Cosa permette la licenza AGPL-3.0

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.

Le risorse da prevedere

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.

L'installazione con Docker Compose

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:

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:

I due segreti vanno in un file .env accanto, che Docker Compose legge da solo. Createlo leggibile solo da root, poi avviate lo stack:

Terminale, in /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

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:

Terminale
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.

Il primo account, i ruoli e gli inviti

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.

Terminale, sul vostro computer
ssh -L 52345:127.0.0.1:52345 root@status.example.com
  1. Aprite http://localhost:52345: Checkmate mostra la sua pagina di registrazione.
  2. Inserite nome, cognome, indirizzo e-mail e una password di almeno 8 caratteri, con una lettera maiuscola, una minuscola, un numero e un carattere speciale.
  3. Registratevi: arrivate sulla dashboard, connessi come Superadmin.

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.

RuoloCosa può fare
UserVedere tutti i monitor, la dashboard, i controlli, gli incidenti, le pagine di stato e le impostazioni, senza modificare nulla
AdminTutto 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
SuperadminTutto 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.

HTTPS: il reverse proxy

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-*.

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

Il vostro primo monitor e i suoi avvisi

  1. In «Uptime», cliccate su «Create monitor» e scegliete HTTP/HTTPS.
  2. Inserite l'indirizzo da controllare, un nome che riconoscerete in un avviso e un intervallo: la documentazione raccomanda da uno a cinque minuti per un servizio critico.
  3. Salvate: Checkmate esegue subito il primo controllo. Sul nostro VPS di test, il monitor risultava attivo un minuto dopo.

Le e-mail: le impostazioni SMTP

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».

I monitor Heartbeat per i vostri job pianificati

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:

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"

Aggiungere /fail, o il codice di uscita del job, all'URL segna subito il monitor come down, senza aspettare che la finestra scada.

Le pagine di stato

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.

I backup

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:

Terminale, in /opt/checkmate
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.

Il ripristino

Sulla stessa installazione o su una nuova, con lo stesso .env, fermate l'applicazione, caricate l'archivio, poi riavviatela:

Terminale, in /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

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.

Gli aggiornamenti

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:

Terminale, in /opt/checkmate
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration

La telemetria

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.

Chi fa che cosa su un VPS gestito

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.

ArgomentoI nostri teamVoi
Il serverAggiornamenti del sistema e della sicurezza, interventi sul server compresiIl momento più adatto alla vostra attività
La supervisioneServer seguito 24 ore su 24, 7 giorni su 7, con intervento senza attendere la vostra chiamataI vostri monitor, avvisi e pagine di stato in Checkmate
CheckmateMonitoraggio proattivo: errori, rallentamenti, database e spazio su disco individuati, correzione raccomandataLa sua installazione, i suoi aggiornamenti e le sue impostazioni, che applicate voi o il vostro assistente IA
Gli utenti e gli avvisiIl server che li ospita, sorvegliato e salvatoGli account, i ruoli, gli inviti e i canali di notifica
I backupOgni notte, cifrati e conservati fuori dalla macchina; ripristino compresoLe esportazioni del database proprie di Checkmate e la richiesta di ripristino, quando ne avete bisogno
La migrazioneIl vostro server attuale migrato, in omaggioIl 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.

Checkmate, su un server gestito per voi

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.

Scoprire i VPS gestiti

Domande frequenti

Checkmate è gratuito?

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.

Come installare Checkmate con Docker Compose?

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.

Quali sono le credenziali predefinite di Checkmate?

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.

Quanta memoria serve a Checkmate?

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.

Come inviare gli avvisi di Checkmate via e-mail?

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.

Come fare il backup di Checkmate?

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.

Come aggiornare Checkmate?

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 Checkmate?

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.

Fonti e documentazione ufficiale

Contattaci