Installazione con Docker

DumbMonit gira in un solo container: il server dumbmonit (raccolta, API, avvisi, interfaccia web) avvia il proprio VictoriaMetrics per l’archiviazione delle serie temporali; il binario è incluso nell’immagine. Configurazione e stato risiedono in un database SQLite integrato. Un solo volume, /data, contiene il database, il segreto dell’istanza e le serie temporali.

Tag dell’immagine

ghcr.io/laupernoe/dumbmonit:latest è l’ultima release taggata (amd64; le immagini arm64 sono per ora sospese); :edge segue l’ultimo commit su dev. Per eseguirlo dai sorgenti, docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build costruisce la stessa immagine in locale (circa dieci minuti la prima volta; serve solo Docker).

Prerequisiti

• Docker Engine con il plugin Compose (docker compose version funziona).
• Una macchina che possa raggiungere i dispositivi che vuoi monitorare. Non deve essere raggiungibile da questi, tranne che per gli agent, che inviano le proprie misurazioni al server via HTTP.
• La porta 8080 libera sull’host, oppure un’altra porta a tua scelta (vedi sotto).

Il file Compose

Questo è l’intero docker-compose.yml (nessun file .env necessario); salvalo in una directory a sé stante:

services:
  dumbmonit:
    image: ghcr.io/laupernoe/dumbmonit:latest
    ports:
      - "8080:8080"
    volumes:
      - dumbmonit-data:/data
      # Or a host directory; on a SELinux host (Fedora, RHEL) add `:Z`:
      # - ./dumbmonit:/data:Z
    # environment:
    #   PUID: "1000"   # owner of the files in /data (default 65532)
    #   PGID: "1000"
    restart: unless-stopped
    stop_grace_period: 30s
    read_only: true
    tmpfs: [/tmp]
    # Starts as root only to give /data to user 65532 (or PUID/PGID), then
    # drops root for good: a host directory works as it is. Remove `user` and
    # `cap_add` to run as 65532 from the start (the files must belong to it).
    user: "0:0"
    cap_drop: [ALL]
    cap_add: [CHOWN, DAC_READ_SEARCH, SETUID, SETGID]
    security_opt: ["no-new-privileges:true"]
    sysctls:
      net.ipv4.ping_group_range: "0 2147483647"

volumes:
  dumbmonit-data:
    name: dumbmonit-data

Poi avvialo:

docker compose up -d

Viene scaricata l’immagine pubblicata; il file system in sola lettura, le capability, PUID/PGID e la sysctl ping_group_range sono spiegati in Permessi e directory dei dati e Ping ICMP senza capability. Le opzioni (porta, segreto, retention, VictoriaMetrics esterno, screenshot) sono variabili d’ambiente che aggiungi tu.

Costruire l’immagine da sé

Da un clone del repository, docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build costruisce invece la stessa immagine in locale (circa dieci minuti a freddo; sull’host non serve nessuna toolchain Rust o Node). Usalo per eseguire dai sorgenti o da un branch.

VictoriaMetrics integrato

L’immagine contiene il binario di VictoriaMetrics (/victoria-metrics-prod, da victoriametrics/victoria-metrics:v1.152.0). Quando DUMBMONIT_VM_URL non è impostata, il server lo avvia come processo figlio in ascolto su 127.0.0.1:8428, salva le sue serie in /data/vm, inoltra le sue righe di log nel proprio log, lo riavvia con un backoff se muore e lo ferma allo spegnimento. Nulla viene pubblicato: la porta resta dentro il container.

Vale la pena conoscere due variabili: DUMBMONIT_VM_RETENTION (12 mesi per impostazione predefinita; vanno bene anche 30d o 2y) e DUMBMONIT_VM_MEMORY (256MB, il budget delle sue cache; aumentalo per centinaia di host). Il resto è nel riferimento della configurazione.

Per usare un VictoriaMetrics che già gestisci, imposta DUMBMONIT_VM_URL al suo indirizzo (http://host:8428): quello integrato non viene più avviato e /data/vm resta vuota.

Primo avvio

Apri https://<your-host>:8080. Il browser mostra un avviso una sola volta per il certificato autofirmato (vedi HTTPS and encryption). Un’istanza nuova mostra la schermata /setup, dove crei il primo account amministratore (password di almeno 12 caratteri).

La schermata chiede prima di tutto il codice di setup. Finché non esiste alcun amministratore, il server stampa nei log all’avvio un codice monouso:

docker compose logs dumbmonit | grep -A1 "setup code"

  First-run setup code: K7XQ4-M9PRT

Dimostra che chi crea l’account admin controlla il server, così nessun altro sulla rete può impossessarsi per primo di un’istanza nuova. Il codice vive solo in memoria, cambia a ogni riavvio finché non esiste un admin, e i tentativi errati sono soggetti a rate limit. Per un deployment automatizzato, imposta DUMBMONIT_SETUP_CODE per sceglierlo tu.

Poi aggiungi il tuo primo monitor: vedi Aggiungi il tuo primo monitor.

Variabili d’ambiente

Tutto passa dalle variabili d’ambiente; nessuna è obbligatoria. Aggiungi quelle che ti servono sotto environment: del servizio, come mostrato in Opzioni avanzate.

Variabile	Predefinito	Ruolo
DUMBMONIT_BIND	0.0.0.0:8080	Indirizzo di ascolto dentro il container.
PUID / PGID	65532	Con user: "0:0": utente e gruppo con cui gira il server, e proprietario dei file in /data (dettagli). Funzionano anche DUMBMONIT_PUID / DUMBMONIT_PGID.
DUMBMONIT_DATA_DIR	/data	Database SQLite (dumbmonit.db), segreto dell’istanza (secret.key) e dati del VictoriaMetrics integrato (vm/).
DUMBMONIT_VM_URL	(non impostata)	URL di un VictoriaMetrics esterno. Se impostata, quello integrato non viene avviato.
DUMBMONIT_VM_RETENTION	12	Retention del VictoriaMetrics integrato: mesi, oppure 30d, 2y.
DUMBMONIT_VM_MEMORY	256MB	Budget di memoria delle cache del VictoriaMetrics integrato.
DUMBMONIT_VM_LISTEN	127.0.0.1:8428	Indirizzo di ascolto del VictoriaMetrics integrato, dentro il container.
DUMBMONIT_SECRET	(generato)	Segreto dell’istanza che cifra le credenziali dei monitor e i token.
DUMBMONIT_MAX_CONCURRENT_PROBES	64	Sonde concorrenti, tutti i collector insieme.
DUMBMONIT_PROBE_TIMEOUT_SECS	10	Durata massima di una sonda.
DUMBMONIT_FLUSH_INTERVAL_SECS	5	Periodo di scrittura verso VictoriaMetrics.
DUMBMONIT_LOG	info	Filtro dei log (sintassi tracing, es. debug, dumbmonit=trace).
DUMBMONIT_AGENT_DIR	/agents	Binari degli agent serviti sotto /download/….
DUMBMONIT_RESET_PASSWORD	(vuota)	Impostala a 1 per cancellare la password e tutte le sessioni all’avvio.
DUMBMONIT_SETUP_CODE	(generato)	Codice di setup richiesto da /setup finché non esiste un admin. Se non impostata, ne viene stampato uno casuale nei log a ogni avvio.
DUMBMONIT_COOKIE_SECURE	(disattivata)	Impostala a 1 dietro un reverse proxy TLS per marcare il cookie di sessione come Secure.
DUMBMONIT_ALERT_INTERVAL_SECS	30	Periodo di valutazione degli avvisi (mai sotto 10).
DUMBMONIT_ALERT_HISTORY_DAYS	90 giorni	Retention dello storico degli avvisi. Vedi il riferimento della configurazione per un’avvertenza sulla sua unità.
DUMBMONIT_BACKUP_ENABLED	attiva	Backup locali pianificati del database in /data/backups/. DUMBMONIT_BACKUP_DIR, _INTERVAL_HOURS (24) e _KEEP (7) li regolano; vedi Backup e ripristino.

L’elenco completo, con i dettagli, è nel riferimento della configurazione. I nomi EZYMONIT_* precedenti alla ridenominazione sono ancora letti come fallback; vedi Aggiornamento.

Fai il backup della chiave segreta

Le community SNMP, le password e i token API sono cifrati con AES-256-GCM usando una chiave derivata dal segreto dell’istanza. Al primo avvio, DumbMonit genera questo segreto in /data/secret.key (dentro il volume dumbmonit-data).

Fai il backup di secret.key insieme al database

Senza di essa, le credenziali dei monitor sono irrecuperabili: un database ripristinato da solo dà un’istanza che non può comunicare con nulla. Il server rileva all’avvio una chiave mancante o modificata e rifiuta di continuare con un messaggio esplicito, invece di fallire in silenzio a ogni sonda. I backup pianificati la copiano per te — vedi Backup e ripristino.

Se preferisci gestire tu il segreto, imposta invece DUMBMONIT_SECRET nel file Compose (esempio) (32 caratteri casuali o più). Conservalo nel tuo gestore di password.

Aggiornamento

docker compose pull
docker compose up -d

Le migrazioni del database vengono eseguite all’avvio. I dati di VictoriaMetrics non vengono toccati.

Fai prima un backup

Settings → Backup → Back up now scrive in pochi secondi una copia coerente del database e di secret.key in /data/backups/, ed è da lì che ripristini se l’aggiornamento va male. Vedi Backup e ripristino.

Bind mount

Un docker-compose.yml esistente continua a funzionare così com’è: l’immagine gira ancora con l’utente 65532. Il nuovo file aggiunge user: "0:0" e una riga cap_add perché una directory dell’host funzioni senza preparazione (Permessi); copia queste due righe se vuoi passare a un bind mount.

Da EzyMonit e dalla configurazione a due container

DumbMonit si chiamava EzyMonit fino a settembre 2026, e girava come due container, il server e un servizio victoriametrics separato. Per aggiornare i dati del vecchio progetto vanno spostati una volta nel nuovo volume. Il vecchio progetto si chiamava ezymonit (i suoi volumi ezymonit_ezymonit-data e ezymonit_vm-data; docker volume ls lo conferma). Dalla vecchia directory:

docker compose down

Poi, con il nuovo docker-compose.yml:

docker volume create dumbmonit-data
docker run --rm -v ezymonit_ezymonit-data:/from -v dumbmonit-data:/to alpine cp -a /from/. /to/
docker run --rm -v ezymonit_vm-data:/from -v dumbmonit-data:/to alpine sh -c 'mkdir -p /to/vm && cp -a /from/. /to/vm/'
docker compose up -d

La vecchia directory dati di VictoriaMetrics ha il layout usato da quello integrato: nulla da convertire. L’alternativa è tenere il VictoriaMetrics esterno e puntarvi DUMBMONIT_VM_URL.

Ciò che il server gestisce da solo al primo avvio:

• Le variabili EZYMONIT_* sono ancora lette come fallback, con un avviso all’avvio per variabile (EZYMONIT_X is deprecated, use DUMBMONIT_X).
• /data/ezymonit.db viene rinominato in dumbmonit.db.
• I token agent ezym_… continuano a funzionare; i nuovi sono dmon_…. Gli agent continuano a inviare i dati; riesegui il comando di installazione su ogni macchina quando ti è comodo, migra il vecchio servizio sul posto.
• Il cookie di sessione ha cambiato nome: tutti devono accedere di nuovo una volta. La preferenza di tema del browser viene mantenuta.

Ciò che non gestisce: il prefisso delle metriche è cambiato da ezymonit_ a dumbmonit_ senza alcuna compatibilità. Le vecchie serie restano in VictoriaMetrics con il vecchio nome e scadono con la retention; i grafici e le regole integrate ripartono dall’aggiornamento. Le regole di allerta personalizzate che nominano metriche ezymonit_… vanno modificate.

Backup e ripristino

Un solo volume nominato, dumbmonit-data, contiene tutto:

Percorso	Contenuto
dumbmonit.db	Monitor, regole, canali, stato degli avvisi, sessioni.
secret.key	Il segreto dell’istanza.
backups/	I backup locali pianificati: una copia del database e del segreto, giornaliera per impostazione predefinita, sette conservate.
vm/	Le serie temporali di VictoriaMetrics (12 mesi di retention per impostazione predefinita).

DumbMonit esegue il backup del proprio database in modo pianificato, ed esporta l’intera configurazione — monitor, credenziali, regole, canali — in un unico file cifrato con una passphrase a tua scelta, che si ripristina su un’istanza nuova. Entrambi sono in Backup e ripristino, insieme a cosa fare prima di un aggiornamento e all’unica regola su secret.key che vale la pena leggere due volte.

Per archiviare il volume stesso, grafici compresi, ferma lo stack e crea un tar:

docker compose stop
docker run --rm -v dumbmonit-data:/data -v "$PWD:/backup" alpine \
  tar czf /backup/dumbmonit-data.tgz -C /data .
docker compose start

Per ripristinare, crea il volume, estrai l’archivio al suo interno nello stesso modo, poi docker compose up -d.

Se lo spazio conta, --exclude=./vm mantiene l’archivio piccolo: il database e il segreto sono la configurazione, vm/ sono solo i grafici.

Opzioni avanzate

Il file Compose qui sopra non contiene variabili, volutamente. Per cambiare un’impostazione, aggiungi un blocco environment: (o una riga al suo interno) sotto dumbmonit: nel tuo docker-compose.yml, poi esegui di nuovo docker compose up -d. Il container viene ricreato; il volume dei dati resta.

Un’altra porta. Cambia il lato sinistro della mappatura; il container continua ad ascoltare sulla 8080:

    ports:
      - "8099:8080"

Un segreto tuo, al posto di quello generato in /data/secret.key. Cifra le credenziali dei monitor: perderlo significa reinserirle tutte.

    environment:
      DUMBMONIT_SECRET: replace-me-with-32-random-characters

Retention e memoria del VictoriaMetrics integrato (mesi, oppure 30d / 2y; un homelab di qualche decina di monitor sta in 256 MB):

    environment:
      DUMBMONIT_VM_RETENTION: "24"
      DUMBMONIT_VM_MEMORY: 512MB

VictoriaMetrics esterno; quello integrato non viene più avviato:

    environment:
      DUMBMONIT_VM_URL: http://victoriametrics:8428

Password dimenticata. Aggiungi la riga qui sotto, esegui docker compose up -d, ricrea il primo amministratore nella UI (monitor, regole e canali restano), poi rimuovi la riga ed esegui ancora una volta docker compose up -d:

    environment:
      DUMBMONIT_RESET_PASSWORD: "1"

Screenshot delle modifiche ai siti web: un Chromium headless accanto al server; vedi sotto Screenshot delle modifiche ai siti web.

Altre variabili: riferimento della configurazione.

Screenshot delle modifiche ai siti web

Il monitor delle modifiche ai siti web confronta sempre il testo visibile delle pagine. Conservare uno screenshot di ogni nuova versione richiede un browser, e l’immagine di DumbMonit non ne contiene: un Chromium headless gira come secondo servizio, e DUMBMONIT_BROWSER_URL indica al server dove trovarlo.

Aggiungi queste righe al tuo docker-compose.yml, poi esegui docker compose up -d:

services:
  dumbmonit:
    environment:
      DUMBMONIT_BROWSER_URL: http://browser:9222
  browser:
    image: chromedp/headless-shell:stable
    shm_size: 256m
    restart: unless-stopped

• browser è il nome del servizio; sulla rete Compose, http://browser:9222 porta a lui. Nulla pubblica la sua porta: solo DumbMonit gli parla.
• shm_size: 256m: Chromium esegue il rendering in /dev/shm, e i 64 MB predefiniti di Docker sono troppo pochi per una pagina lunga.
• Va bene qualsiasi Chromium avviato con --remote-debugging-port; qui si usa l’immagine chromedp/headless-shell.

Senza browser, tutto il resto funziona come sempre (confronto del testo, avvisi, copie prima/dopo); le istantanee semplicemente non hanno immagine. Finché il server non raggiunge un browser, il modulo di un monitor di modifiche ai siti web mostra un avviso con queste righe. Se l’avviso resta dopo il riavvio, controlla docker compose logs browser, che il nome host di DUMBMONIT_BROWSER_URL sia il nome del servizio e che i due servizi siano nello stesso progetto Compose.

Reverse proxy

La UI e l’API sono servite su un’unica porta, che accetta solo HTTPS (una richiesta HTTP semplice riceve un reindirizzamento, vedi HTTPS and encryption). Un reverse proxy deve quindi connettersi al container in HTTPS (https://dumbmonit:8080), con la verifica del certificato disattivata per quel tratto oppure con il certificato di DumbMonit attendibile. Non viene usato alcun WebSocket: l’interfaccia interroga l’API a intervalli, quindi qualsiasi reverse proxy funziona senza configurazione particolare.

monit.example.com {
    reverse_proxy https://127.0.0.1:8080 {
        transport http {
            tls_insecure_skip_verify
        }
    }
}

server {
    listen 443 ssl;
    server_name monit.example.com;
    # ssl_certificate / ssl_certificate_key …

    location / {
        proxy_pass https://127.0.0.1:8080;
        proxy_ssl_verify off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Gli agent inviano batch di recupero dopo un'interruzione:
        client_max_body_size 16m;
    }
}

Quando il proxy termina il TLS, imposta DUMBMONIT_COOKIE_SECURE: "1" così il cookie di sessione viene inviato solo su HTTPS. Impostala solo se ogni browser raggiunge DumbMonit in HTTPS: il browser non rimanderebbe mai il cookie e il login sarebbe impossibile.

Agent dietro un proxy

Il comando di installazione mostrato quando crei un token agent usa l’URL che il tuo browser ha usato per raggiungere la UI. Se è l’URL del proxy, anche gli agent lo useranno: assicurati che /install.sh, /install.ps1, /download/… e /api/ingest passino attraverso il proxy.

Permessi e directory dei dati

Il server non gira mai come root. Per impostazione predefinita l’immagine gira con l’utente 65532:65532, a cui appartiene già un volume con nome creato da Docker.

Un bind mount (./dumbmonit:/data), invece, mantiene il proprietario della directory dell’host, spesso root quando l’ha creata Docker. Per questo il file Compose qui sopra avvia il container come root (user: "0:0"). Il server resta root solo per un istante: prima di aprire il database, avviare VictoriaMetrics o mettersi in ascolto sulla rete, cede /data a 65532:65532 (solo le voci che appartengono a qualcun altro, senza seguire i link simbolici), abbandona root per sempre e verifica di non poterlo riottenere. Le quattro capability di cap_add servono solo a questo passo; dopo non ne resta nessuna. no-new-privileges e il file system root in sola lettura restano attivi: /data e /tmp sono gli unici percorsi scrivibili.

Scegliere il proprietario: PUID e PGID. Con user: "0:0", indica l’uid e il gid con cui gira il server; i file vengono ceduti a loro all’avvio:

    environment:
      PUID: "1000"
      PGID: "1000"

Funzionano anche DUMBMONIT_PUID / DUMBMONIT_PGID e hanno la precedenza. 0 viene rifiutato. Su Unraid, PUID=99 e PGID=100 corrispondono al proprietario abituale di appdata. Senza user: "0:0", PUID/PGID vengono ignorati.

Senza user: "0:0" (un semplice docker run -v ./data:/data, o --user 1000:1000) nessun proprietario cambia e /data deve essere già scrivibile. In caso contrario il server si ferma e suggerisce prima --user 0:0, poi sudo chown -R 65532:65532 ./data sull’host per un bind mount o, per un volume con nome:

docker run --rm -v dumbmonit-data:/data alpine chown -R 65532:65532 /data

SELinux e Podman

Su un host dove SELinux è in modalità enforcing (Fedora, RHEL, CentOS Stream, AlmaLinux…), un bind mount viene negato al container, root compreso, finché non porta un’etichetta di container. Aggiungi :Z al volume, oppure :z se altri container condividono la directory:

    volumes:
      - ./dumbmonit:/data:Z

Senza, il server si ferma con the host enforces SELinux and the volume has no container label. I volumi nominati sono etichettati da Docker e non richiedono nulla.

Podman rootless funziona allo stesso modo, con --user 0:0. Root nel container è il tuo utente sull’host, e i file di un bind mount vanno all’uid 65532 del container, che l’host mostra come uno dei tuoi sub-uid (165531 con il solito /etc/subuid). Leggili con podman unshare ls -l ./dumbmonit. Per tenerli invece sotto il tuo uid, esegui il container come te stesso; allora nessun proprietario cambia:

podman run --userns keep-id --user "$(id -u):$(id -g)" -v ./dumbmonit:/data:Z …

Ping ICMP senza capability

Il monitor ping invia echo ICMP. Invece di un raw socket — che richiede NET_RAW, e una capability concessa a un utente non root del container non è comunque utilizzabile — usa un socket ICMP echo, che Linux consente ai gruppi elencati in net.ipv4.ping_group_range. Il file Compose imposta quella sysctl nel network namespace del container stesso:

services:
  dumbmonit:
    sysctls:
      net.ipv4.ping_group_range: "0 2147483647"

Sull’host non cambia nulla. Docker 20.10 e successivi impostano da soli questo intervallo in ogni container; le righe esplicite lo garantiscono anche sui motori più vecchi e su Podman. Senza, il controllo segnala un errore di configurazione (mostrato sul monitor, non notificato), mai un falso “host down”. Con docker run, passa --sysctl net.ipv4.ping_group_range="0 2147483647". Finché il server non riesce ad aprire un socket ICMP, il modulo di un monitor ping mostra un avviso con queste righe.

Provare senza hardware

Aggiungi un monitor demo: produce misurazioni finte senza nulla da preparare, così grafici, regole e notifiche si possono provare subito. Per dati SNMP reali, spesso basta la macchina che esegue Docker — installaci snmpd (apt install snmpd, consenti la community public sul bridge Docker in /etc/snmp/snmpd.conf) e aggiungi un dispositivo SNMP con l’indirizzo dell’host su quel bridge (172.17.0.1 per impostazione predefinita): il profilo viene rilevato automaticamente e compaiono interfacce, memoria e processi.

Gli sviluppatori possono aggiungere l’overlay docker-compose.dev.yml per pubblicare il VictoriaMetrics integrato sulla porta :8428 dell’host per query MetricsQL dirette:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d