Nel mondo dell'automazione e della gestione di sistemi, ci affidiamo sempre più a script e processi pianificati per svolgere compiti cruciali. Ma cosa succede se uno di questi script fallisce silenziosamente, o semplicemente non si avvia come previsto? Rilevare questi problemi in tempo è fondamentale per garantire l'affidabilità e la stabilità dei nostri sistemi.

È qui che entra in gioco HealthChecks, un potente strumento open-source che ti permette di monitorare l'esecuzione dei tuoi script, cron job e servizi, avvisandoti proattivamente in caso di malfunzionamenti o ritardi.

In questa guida completa, vedremo passo dopo passo il processo di installazione e configurazione di HealthChecks, dalla preparazione del database MariaDB fino all'impostazione dei primi controlli e alla gestione degli utenti. Ci prepariamo a semplificare la supervisione dei nostri processi e a migliorare la robustezza del nostro homelab!

Prerequisiti

Per installare HealthChecks avrete bisogno di:

• Un host con S.O. Linux (in questa guida, utilizzeremo Ubuntu Server 24.04). Per quanto riguarda le risorse, HealthChecks non pretende molto. 2 vCPU e 1GB di RAM saranno più che sufficienti.
• Installare Python, Django e MariaDB sulla macchina Ubuntu, ma non vi preoccupate perché vedremo insieme come farlo.
• Per poter comunicare con HealthChecks, i vostri script dovranno poter raggiungere l'indirizzo IP della macchina Ubuntu, sulla porta 8000.

Tutto pronto? Iniziamo!

Installazione

(procedura testata su Ubuntu Server 24.04)

In questa fase, installeremo i pacchetti essenziali per il funzionamento di HealthChecks: MariaDB (il motore di database), UWSGI (il server web) e HealthChecks stesso. Configureremo inoltre il servizio per l'avvio automatico.

MariaDB

1. Installazione

• Esegui i seguenti comandi per installare MariaDB ed avviare la procedura guidata di configurazione

sudo apt update
sudo apt install mariadb-server
sudo mysql_secure_installation

Verranno richieste varie informazioni, compiliamole come segue:

• Database root password: NONE
• Switch to unix_socket authentication: NO
• Change the root password: NO
• Remove anonymous users: YES
• Disallow root login remotely: YES
• Remove test database and access to it: YES
• Reload privilege tables now: YES

2. Creazione dell'utente admin

• Apriamo la console di MariaDB

sudo mariadb

• Diamo all'utente admin i permessi su tutte le tabelle, sostituendo {password} con la password da assegnare all'utente

GRANT ALL ON *.* TO 'admin'@'localhost' IDENTIFIED BY '{password}' WITH GRANT OPTION;

• Applichiamo le modifiche effettuate

FLUSH PRIVILEGES;

• Usciamo dalla shell di MariaDB

exit

3. Test di funzionamento

• Controlliamo lo stato del servizio

sudo systemctl status mariadb

• Controlliamo la versione

sudo mysqladmin version

4. Creazione DB ed utenti

• Apriamo nuovamente la console di MariaDB

sudo mariadb

• Creiamo il database healthchecks e due utenti - healthchecks e test_healthchecks - tramite questi comandi, sostituendo {password} con le password da assegnare agli utenti

CREATE DATABASE healthchecks;
GRANT ALL PRIVILEGES ON healthchecks.* TO 'healthchecks'@'localhost' IDENTIFIED BY '{password}';
GRANT ALL PRIVILEGES ON test_healthchecks.* TO 'healthchecks'@'localhost' IDENTIFIED BY '{password}';
FLUSH PRIVILEGES;
exit

HealthChecks

Adesso installeremo HealthChecks.

1. Creazione cartella di installazione e utente di sistema

• Creiamo una cartella healthchecks in /opt/

sudo mkdir /opt/healthchecks

• Creiamo un utente di sistema healthchecks con login disabilitato

sudo adduser --system --group --home /opt/healthchecks --shell /usr/sbin/nologin healthchecks

• Assegniamo all'utente healthchecks la proprietà della cartella ed impostiamo permessi limitati

sudo chown root:healthchecks /opt/healthchecks
sudo chmod 0770 /opt/healthchecks

2. Installazione dipendenze

• Installiamo tramite apt i pacchetti di Python necessari

sudo apt install gcc git python3-dev python3-venv libcurl4-gnutls-dev librtmp-dev default-libmysqlclient-dev python3-pip

• Spostiamoci nella cartella che abbiamo creato al punto precedente

cd /opt/healthchecks

• Scarichiamo il progetto di HealthChecks da Github

git clone https://github.com/healthchecks/healthchecks.git

• modifichiamo il file requirements.txt

sudo nano healthchecks/requirements.txt

• eliminiamo la riga contenente psycopg2

• Installiamo le dipendenze di mysqlclient

sudo apt-get install pkg-config python3-dev default-libmysqlclient-dev build-essential

• Tramite pip (il Package Manager di Python), installiamo i seguenti pacchetti

sudo pip install wheel mysqlclient uwsgi --break-system-packages

• Installiamo i requisiti di HealthChecks

sudo pip install -r healthchecks/requirements.txt --break-system-packages

3. Test di funzionamento dell'installazione

Per testare il funzionamento della release di HealthChecks appena installata, e per assicurarci di aver installato correttamente tutti i pacchetti necessari, eseguiamo i seguenti comandi:

• Creiamo alcune variabili d'ambiente per effettuare i test

export DB=mysql
export DB_NAME=healthchecks
export DB_PASSWORD={la_tua_password_per_l_utente_healthchecks_di_mariadb}
export DB_USER=healthchecks

• Eseguiamo le migrazioni di Django, che fornisce il Backend a HealthChecks

sudo python3 ./manage.py migrate
sudo python3 ./manage.py createsuperuser

Verranno richiesti alcuni dati:

• email address: l'indirizzo email da assegnare all'account root
• password: la password da assegnare all'account root
• Effettuiamo i test automatici di Django

sudo python3 ./manage.py test

Se non riscontriamo errori, possiamo procedere con la configurazione del servizio.

4. Impostazione parametri

• Apriamo la shell di Python

sudo python3

• Eseguiamo i comandi seguenti per utilizzare una funzione di gestione di Django che genererà una secret key univoca da indicare su HealthChecks

from django.core.management.utils import get_random_secret_key  
get_random_secret_key()

• Annotiamoci il risultato dell'ultimo comando ed usciamo dalla console Python premendo CTRL + D
• Creiamo e modifichiamo il file .env da far leggere ad HealthChecks

sudo touch /opt/healthchecks/.env
sudo nano /opt/healthchecks/.env

• Compiliamolo come segue

ADMINS={email dell'utente root creato prima}
ALLOWED_HOSTS={FQDN.del.server}:8000,{indirizzo.IP.del.Server}:8000,localhost
DB=mysql
DB_NAME=healthchecks
DB_PASSWORD={password dell'utente di MariaDB, racchiuso tra apici 'password'}
DB_USER=healthchecks
DEBUG=True
DEFAULT_FROM_EMAIL={indirizzo mittente delle email}
EMAIL_HOST_PASSWORD={password del server di posta}
EMAIL_HOST_USER={utente del server di posta}
EMAIL_PORT={porta SMTP del server di posta}
EMAIL_USE_TLS=True
EMAIL_USE_VERIFICATION=False #Impostare a True per richiedere conferma di ricezione email all'aggiunta di un nuovo destinatario
REGISTRATION_OPEN=False
SECRET_KEY={la secret key di Django generata prima, racchiusa tra apici 'secretkey'}
SERVER_EMAIL={indirizzo mittente delle email}
SHELL_ENABLED=True
SITE_NAME='HealthChecks'
SITE_ROOT={FQDN.del.Server}:8000
APPRISE_ENABLED = False #Impostare a True se si vogliono abilitare le notifiche Telegram (vedi capitolo \"Configurazione notifiche Telegram\")

• Parametri email specifici per utilizzare Gmail come email di sistema:

DEFAULT_FROM_EMAIL={[email protected]}
EMAIL_HOST_PASSWORD={app password di google racchiusa tra apici 'app password google'}
EMAIL_HOST_USER={[email protected]}
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=465
EMAIL_USE_TLS=False
EMAIL_USE_SSL=True
EMAIL_USE_VERIFICATION=False

Apprise - come inviare notifiche verso qualsiasi servizio di messaggistica

Scopri Apprise, lo strumento che unifica tutte le tue notifiche. Invia messaggi a email, Telegram, Slack e decine di altri servizi con una singola chiamata API. Semplifica i tuoi script, risparmia tempo e centralizza la gestione degli avvisi in un unico posto.

Firenetwork - BlogSamuele Gabbrielli

• Chiudiamo l'accesso al file di configurazione

sudo chmod 0600 /opt/healthchecks/.env

Impostazione di UWSGI

• Creiamo e modifichiamo il file di configurazione

sudo touch /opt/healthchecks/uwsgi.ini
sudo nano /opt/healthchecks/uwsgi.ini

• Compiliamo il file come segue:

[uwsgi]
strict
master
die-on-term
http-socket = 0.0.0.0:8000
harakiri = 10
post-buffering = 16192
processes = 4
auto-procname
enable-threads
threads = 1
chdir = /opt/healthchecks/healthchecks
module = hc.wsgi:application
thunder-lock
disable-write-exception

max-fd = 10000

check-static = static-collected/
static-gzip-dir = static-collected/CACHE

hook-pre-app = exec:python3 ./manage.py migrate
attach-daemon = python3 ./manage.py sendalerts
attach-daemon = python3 ./manage.py sendreports --loop

if-env = SMTPD_PORT
attach-daemon = python3 ./manage.py smtpd --port %(_)\nendif =

Creazione servizio per l'avvio automatico

Adesso creeremo un servizio per avviare HealthChecks al boot

• Controlliamo dove è stato installato uwsgi

which uwsgi

• Creiamo il file del servizio, in /etc/systemd/system/

sudo nano /etc/systemd/system/healthchecks.service

• Compiliamolo come segue:

[Unit]
Description=Healthchecks Server
After=network.target

[Service]
User=healthchecks
Group=healthchecks

NoNewPrivileges=true
PrivateDevices=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full

EnvironmentFile=/opt/healthchecks/.env
ExecStart={path/di/uwsgi} /opt/healthchecks/uwsgi.ini
KillSignal=SIGINT
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

• Abilitiamo il servizio

sudo systemctl enable healthchecks.service --now

Adesso possiamo testare se andando su http://Indirizzo.IP.del.server:8000 il sito risponde. Se veniamo accolti dalla schermata di login di HealthChecks (Mychecks) allora abbiamo fatto un bel lavoro!

Configurazione

Passare da debug a produzione

Di default, HealthChecks è in modalità di debug. Per passare alla modalità di produzione, è necessario modificare il file .env e impostare la variabile DEBUG su False.

Cogliamo questa occasione per caricare -opzionalmente- un logo personalizzato da avere su HealthChecks.

• Stoppiamo il servizio

sudo systemctl stop healthchecks.service

• Copiamo il logo da applicare ad HealthChecks, rinominandolo in "logo.png" e copiandolo in /opt/healthchecks/healthchecks/static/img/ sovrascrivendo il file già esistente
• Passiamo da debug a produzione

sudo python3 /opt/healthchecks/healthchecks/manage.py collectstatic
sudo python3 /opt/healthchecks/healthchecks/manage.py compress --force

• Modifichiamo il file con le variabili di ambiente di HealthChecks

sudo nano /opt/healthchecks/.env

Impostando DEBUG=True a DEBUG=False

• Riavviamo HealthChecks e verifichiamo il suo funzionamento

sudo systemctl restart healthchecks

Registrare il primo utente

Adesso che abbiamo HealthChecks in modalità di Produzione, possiamo iniziare a registrare gli utenti. Prima di tutto, apriamo le registrazioni (che sono chiuse di default) per creare il nostro primo utente.

• Stoppiamo il servizio

sudo systemctl stop healthchecks.service

• Modifichiamo il file .env

sudo nano /opt/healthchecks/.env

• Modifichiamo la riga REGISTRATION_OPEN=False in REGISTRATION_OPEN=True
• Riavviamo HealthChecks

sudo systemctl restart healthchecks

• Accediamo alla pagina di HealthChecks e premiamo in alto a destra su Sign Up

• Indichiamo l'indirizzo email del nostro primo utente e confermiamo la registrazione tramite il magic link che riceveremo via email

Ora che abbiamo registrato il nostro primo utente, possiamo chiudere nuovamente le registrazioni (le registrazioni dei prossimi utenti verranno fatte dall'utente appena creato).

• Modifichiamo nuovamente il file .env

sudo nano /opt/healthchecks/.env

• Impostiamo REGISTRATION_OPEN=False (le registrazioni dei prossimi utenti verranno fatte dall'utente appena creato)
• Riavviamo HealthChecks

sudo systemctl restart healthchecks

Utilizzo

Impostare l'accesso con email e password

Di default, ci autentichiamo su HealthChecks inserendo la mail e cliccando sul magic link che riceviamo via email. Se invece preferiamo accedere con email e password:

• Accediamo ad HealthChecks tramite magic link
• Premiamo in alto a destra su Account → Account Settings

• Nella sezione Email and Password premiamo su Enable password authentication
• Già che ci siamo, potremmo attivare l'Autenticazione a Due Fattori tramite il pulsante Set Up Authenticator App

Creare un HealthCheck

Accediamo ad HealthChecks e dovremmo trovarci nel nostro progetto di default, My Project. Un progetto è un insieme di HealthCheck, che fanno possibilmente parte dello stesso sistema, processo produttivo, o ambiente.

Ogni progetto ha:

• Uno o più HealthCheck, uno per ogni servizio, script o programma che dobbiamo monitorare.
• Una lista di utenti collegati, che possono visualizzare e modificare gli HealthCheck del progetto a seconda dei loro permessi.
• Una lista di integrazioni, cioè un insieme di metodi di notifica da associare agli HealthChecks.
• Una API Key univoca, che possiamo utilizzare ad esempio per leggere lo stato degli HealthChecks da Prometheus.

Andiamo a creare il nostro primo HealthCheck e vediamo come integrarlo nei nostri script.

• Selezioniamo la scheda Checks e premiamo su Add Check

• Configuriamo i parametri presenti nel wizard di creazione

• Name: il nome dell'HealthCheck. Questo verrà visualizzato nelle notifiche e nella pagina web.
• Slug: opzionale, è la stringa che possiamo utilizzare al posto dell'UUID generato automaticamente per comunicare con questo HealthCheck.
• Schedule: indica tre varie modalità con cui indicare ad HealthChecks quando deve aspettarsi un segnale di HealthCheck. In questo esempio, utilizziamo Simple.
• Period: quanto tempo dovrebbe passare tra un HealthCheck ed un altro. Per esempio, per uno script che viene eseguito ogni 24 ore, indichiamo 1 days.
• Grace Time: quanto tempo attendere un HealthCheck prima di segnalarlo come mancato. È utile impostare questo parametro quando si lavora con operazioni pianificate che possono impiegare un po' di tempo a terminare e mandare il segnale di HealthCheck.
• Salviamo il nostro HealthCheck ed otterremo una riga simile a questa

Utilizzare un HealthCheck

Utilizzo semplice

Per utilizzare questo HealthCheck, ci basta inserire nel nostro script una chiamata HTTP di tipo GET all'URL indicato nella colonna Ping URL. è possibile visualizzare l'URL con l'uuid o con lo slug (se impostato) premendo sul link all'intestazione della colonna.

Inoltre, aprendo la pagina dell'HealthCheck, nella sezione How to Ping e nel pulsante Usage Examples sono presenti ulteriori informazioni ed esempi per Crontab, Bash, Python, Ruby, C# e Powershell.

Un HealthCheck che ha ricevuto un segnale ed è in stato "OK" verrà visualizzato come il seguente:

Mentre un HealthCheck in errore verrà visualizzato con l'icona rossa, come questo:

Inoltre, premendo sull'HealthCheck, possiamo visualizzare lo storico dei segnali ricevuti, e dei cambi di stato dell'HealthCheck

Utilizzo di start, OK, error e log

Mandando delle semplici chiamate HTTP GET all'URL del vostro HealthCheck potremo controllare che il vostro script, programma o la vostra operazione pianificata venga effettivamente eseguita, ma non potremo controllare che l'esecuzione termini correttamente o che non si verifichino errori.

Per fare ciò, possiamo inviare chiamate di tipo diverso a seconda di cosa vogliamo segnalare ad HealthChecks. Vediamo come.

• All'avvio dello script, inviamo una chiamata /start

http://indirizzo.IP.di.healthchecks:80/ping/xxxxxxxxxxxxxxx/start

• Se lo script incappa in un errore, inviamo una chiamata /fail

http://indirizzo.IP.di.healthchecks:80/ping/xxxxxxxxxxxxxxx/fail

• Se vogliamo loggare una informazione su questo HealthCheck, inviamo una chiamata POST all'endpoint /log indicando, nel contenuto della chiamata, il testo da loggare

POST /5bf66975-d4c7-4bf5-bcc8-b8d8a82ea278/log HTTP/1.1
Host: indirizzo.IP.di.healthchecks
Content-Type: text/plain
Content-Length: 11

Hello World

• Quando lo script termina la sua esecuzione, inviamo una chiamata all'endpoint principale

http://indirizzo.IP.di.healthchecks:80/ping/xxxxxxxxxxxxxxx/

Una esecuzione che utilizza tutti e quattro questi stati verrà quindi rappresentata in modo simile a questo:

Creare altri utenti ed associarli al progetto HealthChecks

Creiamo altri utenti da associare al nostro progetto.

• Andiamo su Settings, poi dentro a Team Access premiamo su Invite a Team Member

• Indichiamo l'indirizzo email del nuovo utente, e selezioniamo quali permessi dargli relativamente a questo progetto:
  • Team Member: può creare e modificare HealthChecks e le integrazioni del progetto.
  • Manager: come il Team Member, ma può anche aggiungere e rimuovere utenti dal progetto.
  • Read-only: Può vedere gli HealthChecks e le integrazioni, ma non può modificare niente né utilizzare le API Keys.

Configurazione delle notifiche (integrazioni)

All'interno del progetto, alla tab Integrations al momento abbiamo un segnale di avviso, che ci indica che non abbiamo configurato nessuna integrazione

Premendo sulla scheda Integrations possiamo quindi configurare uno o più canali di notifica.

Nel caso delle Email, queste verranno inviate utilizzando le impostazioni di invio email configurate precedentemente nel file .env

(Opzionale) Configurazione notifiche Telegram

Per inviare notifiche attraverso Telegram o altri servizi non direttamente integrati con HealthChecks, è possibile installare ed integrare Apprise CLI.

Apprise è un software che permette di inviare notifiche a moltissimi servizi tramite semplici configurazioni testuali.

Avevamo già parlato di Apprise, nella sua versione webservice (Apprise API)

Apprise - come inviare notifiche verso qualsiasi servizio di messaggistica

Scopri Apprise, lo strumento che unifica tutte le tue notifiche. Invia messaggi a email, Telegram, Slack e decine di altri servizi con una singola chiamata API. Semplifica i tuoi script, risparmia tempo e centralizza la gestione degli avvisi in un unico posto.

Firenetwork - BlogSamuele Gabbrielli

Vediamo come installare Apprise CLI e come integrarlo con HealthChecks

• Installiamo Apprise tramite pip

sudo pip install apprise --break-system-packages

• Controlliamo di aver impostato il flag APPRISE_ENABLED=True nel file /opt/healthchecks/.env
• Accediamo ad HealthChecks, andiamo su Integrations e premiamo su Add Integration accanto a Apprise.
• Quando richiesto, aggiungiamo una riga seguendo il formato tgram://%BOTTOKEN%/%CHATID%

(Opzionale) Esportazione metriche su Prometheus

• Accediamo ad HealthChecks
• Selezioniamo il progetto corretto
• Andiamo su Settings e, dentro ad API Access, premiamo su Create alla riga API key (read-only)
• Prendiamo nota dell'API Key appena generata
• Prendiamo anche nota dell'ID del progetto, che è visibile in chiaro nell'URL

Adesso andiamo a configurare il job di scraping su Prometheus

• Modifichiamo la configurazione di Prometheus

sudo nano prometheus/prometheus.yml

• Nella sezione scrape_configs creiamo la seguente configurazione, valorizzando {ID_Progetto} e {APIKey} con i valori che abbiamo ottenuto precedentemente:

- job_name: '{nome_progetto}'
  scheme: http
  metrics_path: /projects/{ID_progetto}/metrics/{APIKey}
  static_configs:
  - targets: ['IP.del.server.HealthChecks:porta']

Come resettare la 2FA ad un utente

Nel caso in cui uno degli utenti di HealthChecks perda il metodo per l'autenticazione a due fattori, è possibile disattivare la 2FA a quell'utente modificando il Database di HealthChecks.

Vediamo come fare:

• Accediamo a MariaDB tramite CLI

sudo mariadb

• Selezioniamo il DB di HealthChecks

USE healthchecks

• Visualizziamo la lista degli utenti

SELECT * FROM accounts_profile;

• Annotiamoci l'ID dell'utente a cui va resettata la 2FA
• Eseguiamo il seguente comando indicando l'ID dell'utente a cui resettare la 2FA

UPDATE accounts_profile SET totp=NULL where ID={ID_Utente};

L'utente può ora accedere senza 2FA e può procedere a reimpostarsela.