Uptime Kuma

Strumento di monitoraggio del tempo di attività self-hosted con supporto per HTTP, TCP, DNS, Docker e 90+ servizi di notifica inclusi Slack, Discord e Telegram.

Installation

Docker (Recommended)

# Eseguire Uptime Kuma con archiviazione persistente
docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

# Accedere su http://localhost:3001

Docker — Localhost Only

# Vincolamento solo a localhost (nessun accesso esterno)
docker run -d \
  --restart=always \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Docker Compose

# Scaricare il file di composizione ufficiale
mkdir uptime-kuma && cd uptime-kuma
curl -o compose.yaml \
  https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml

# Avviare il servizio
docker compose up -d

# Accedere su http://localhost:3001

Docker with Container Monitoring

# Montare il socket Docker per il monitoraggio della salute del container
docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Non-Docker Installation

# Requisiti: Node.js 20.4+, Git

# Clonare e configurare
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# Avviare direttamente
node server/server.js

# O utilizzare PM2 per l'operazione in background
npm install -g pm2
pm2 start server/server.js --name uptime-kuma

Basic Commands

Command	Description
`docker run -d -p 3001:3001 louislam/uptime-kuma:2`	Avviare il container Uptime Kuma
`docker compose up -d`	Avviare con Docker Compose
`docker compose down`	Interrompere tutti i servizi
`docker compose logs -f`	Seguire i log dei container
`docker restart uptime-kuma`	Riavviare il container
`docker stop uptime-kuma`	Interrompere il container
`docker start uptime-kuma`	Avviare il container interrotto
`node server/server.js`	Avviare senza Docker
`pm2 start server/server.js --name uptime-kuma`	Avviare con PM2
`pm2 restart uptime-kuma`	Riavviare con PM2
`pm2 stop uptime-kuma`	Interrompere con PM2
`pm2 logs uptime-kuma`	Visualizzare i log PM2

Update Commands

Docker

# Estrarre l'immagine più recente
docker pull louislam/uptime-kuma:2

# Interrompere e rimuovere il container attuale
docker stop uptime-kuma
docker rm uptime-kuma

# Ricreare con la nuova immagine (i dati persistono nel volume)
docker run -d \
  --restart=always \
  -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma \
  louislam/uptime-kuma:2

Docker Compose

# Estrarre e ricreare
docker compose pull
docker compose up -d

Non-Docker

cd uptime-kuma
git fetch --all
git checkout 2.1.3 --force
npm install --production
npm run download-dist
pm2 restart uptime-kuma

Monitor Types

Type	Description
HTTP(S)	Monitorare la disponibilità del sito web e il tempo di risposta
HTTP(S) Keyword	Verificare il testo specifico nel corpo della risposta
HTTP(S) JSON Query	Convalidare i valori della risposta JSON
TCP Port	Verificare se una porta TCP è aperta e reattiva
Ping	Ping ICMP per la disponibilità dell’host
DNS	Monitorare la risoluzione dei record DNS
Docker Container	Monitorare lo stato di salute del container
Steam Game Server	Verificare la disponibilità del server di gioco
MQTT	Monitorare la connettività del broker MQTT
gRPC	Monitorare la salute del servizio gRPC
Radius	Controllo del server di autenticazione RADIUS
GameDig	Monitoraggio del server di gioco (protocolli multipli)
Push	Monitoraggio passivo tramite endpoint heartbeat
Group	Raggruppamento logico dei monitor

Notification Services (90+)

Chat & Messaging

Service	Description
Slack	Webhook dei canali e notifiche bot
Discord	Notifiche dei canali basate su webhook
Telegram	Notifiche API bot
Microsoft Teams	Notifiche del webhook in ingresso
Mattermost	Integrazione della chat self-hosted
Rocket.Chat	Notifiche webhook
Google Chat	Notifiche webhook dello spazio
Matrix	Notifiche della chat decentralizzata

Push & Mobile

Service	Description
Pushover	Notifiche push mobile
Gotify	Server push self-hosted
ntfy	Notifiche pub/sub basate su HTTP
Pushbullet	Notifiche push cross-device
Signal	Notifiche di messaggistica sicura
LINE	Integrazione di LINE Notify

Incident Management

Service	Description
PagerDuty	Avviso di incidenti e on-call
Opsgenie	Gestione degli avvisi e escalation
Squadcast	Gestione degli incidenti
Splunk On-Call	Instradamento degli avvisi VictorOps
Better Stack	Tempo di attività e gestione degli incidenti

Email & Webhooks

Service	Description
SMTP Email	Notifiche email personalizzate
Webhook	Chiamate degli endpoint HTTP personalizzate
Home Assistant	Trigger di automazione della casa intelligente
Apprise	Gateway di notifiche universale

Environment Variables

Variable	Description	Default
`UPTIME_KUMA_PORT`	Porta del server	`3001`
`UPTIME_KUMA_HOST`	Indirizzo di binding	`::`
`DATA_DIR`	Directory di archiviazione dei dati	`./data`
`TZ`	Fuso orario	`UTC`
`UMASK`	Maschera dei permessi del file	`0000`
`NODE_EXTRA_CA_CERTS`	Percorso dei certificati CA personalizzati	—
`SSL_CERT`	Percorso del certificato SSL	—
`SSL_KEY`	Percorso della chiave privata SSL	—

Status Pages

Feature	Description
Multiple Pages	Creare pagine di stato separate per servizi diversi
Custom Domains	Mappare le pagine di stato a nomi di dominio personalizzati
Custom CSS	Personalizzare le pagine di stato con CSS personalizzato
Incident Posts	Creare rapporti di incidenti visibili nella pagina di stato
Maintenance	Pianificare le finestre di manutenzione
Monitor Groups	Organizzare i monitor in gruppi nella pagina di stato

Python API (Automation)

# Installare il client API Python
pip install uptime-kuma-api

API Usage Examples

Operation	Description
Add monitor	Creare i monitor a livello di programmazione
Edit monitor	Aggiornare la configurazione del monitor
Delete monitor	Rimuovere i monitor
Pause/Resume	Attivare/disattivare lo stato del monitor
Get status	Recuperare lo stato attuale del monitor
Add notification	Configurare i provider di notifica
Get uptime	Interrogare le statistiche di tempo di attività

Docker Compose Configuration

# compose.yaml
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: always
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
      # Facoltativo: Monitoraggio del container Docker
      # - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - TZ=UTC

Security Configuration

Feature	Description
2FA	Autenticazione a due fattori per l’accesso
Reverse Proxy	Distribuzione dietro Nginx, Caddy o Traefik
SSL/TLS	SSL integrato o terminazione del proxy inverso
Login Rate Limiting	Protezione del brute-force
API Keys	Accesso all’API basato su token

Reverse Proxy Setup

Nginx

server {
    listen 443 ssl;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Backup & Restore

Command	Description
`docker cp uptime-kuma:/app/data ./backup`	Backup della directory dei dati
`docker cp ./backup/. uptime-kuma:/app/data`	Ripristino dal backup
`docker volume inspect uptime-kuma`	Trovare il punto di montaggio del volume

Troubleshooting

Issue	Solution
Impossibile accedere all’interfaccia utente	Verificare il binding della porta: `docker port uptime-kuma`
Errori di volume NFS	Utilizzare le directory locali, non i file system di rete
Errori WebSocket	Configurare il proxy inverso per l’aggiornamento WebSocket
Container non avviato	Verificare i log: `docker logs uptime-kuma`
Persistenza dei dati persa	Assicurarsi che il volume `-v uptime-kuma:/app/data` sia utilizzato
Monitoraggio Docker non riuscito	Montare docker.sock: `-v /var/run/docker.sock:/var/run/docker.sock:ro`

Supported Platforms

Platform	Status
Linux (x64, ARM)	Supported
Windows 10+ (x64)	Supported
macOS	Supported
Docker Desktop	Supported
Kubernetes	Via Docker image
FreeBSD/OpenBSD	Not supported
Replit/Heroku	Not supported

Best Practices

Utilizzare i volumi Docker (non bind mount per NFS) per la persistenza dei dati
Distribuire dietro un proxy inverso con terminazione SSL per l’uso in produzione
Abilitare 2FA per l’account amministratore immediatamente dopo il primo accesso
Impostare gli intervalli di monitoraggio su 60 secondi o più per i servizi esterni
Utilizzare il tipo di monitor Push per i servizi dietro i firewall
Configurare almeno 2 canali di notifica per la ridondanza
Creare pagine di stato separate per il pubblico interno e esterno
Eseguire il backup della directory dei dati regolarmente — contiene tutta la configurazione
Impostare il fuso orario tramite la variabile di ambiente TZ in modo che corrisponda al vostro centro operativo