Ospitare Umami su un VPS gestito: le vostre statistiche web sul vostro server

Che cosa fa Umami

Umami è una piattaforma open source di analisi web e di prodotto. La sua documentazione descrive uno strumento che riunisce traffico, campagne, comportamento dei visitatori, conversioni, fidelizzazione e ricavi, dalla prima visita ai risultati che contano per la vostra attività. È scritto in TypeScript su Next.js, e la sua immagine Docker gira con un account non privilegiato.

• L'acquisizione: pagine viste, visitatori, siti di provenienza, paesi, dispositivi e attività in tempo reale, con campagne UTM, link brevi e pixel di tracciamento.
• Il comportamento: eventi personalizzati, percorsi, registrazioni delle sessioni, mappe di calore, segmenti, coorti e fidelizzazione.
• La conversione: obiettivi, funnel, attribuzione e monitoraggio dei ricavi per pagina e per campagna.
• La condivisione: bacheche, team, un URL di condivisione pubblico, un'API e un server MCP in sola lettura per il vostro assistente IA.
• I siti moderni: la FAQ indica che Umami segue da solo la navigazione tra le pagine nelle applicazioni a pagina singola, senza impostazioni aggiuntive.

Un'istanza segue più siti: ognuno riceve il proprio ID e il proprio script di tracciamento, e i vostri colleghi si orientano grazie agli account e ai team.

Che cosa consente la licenza MIT

Umami è pubblicato con la licenza MIT, a nome di Umami Software, Inc. Concede gratuitamente il diritto di usare, copiare, modificare, unire, pubblicare, distribuire, concedere in sublicenza e vendere copie del software. Potete quindi farlo girare per la vostra azienda e per i siti dei vostri clienti, senza alcuna licenza da acquistare.

La sua unica condizione: l'avviso di copyright e l'avviso di autorizzazione accompagnano tutte le copie o le parti sostanziali del software. Come ogni licenza MIT, fornisce il software «così com'è», senza garanzia.

Cookie e dati personali: che cosa dice il progetto

La documentazione presenta Umami come un sistema di analisi senza cookie, senza tracciamento tra siti e senza raccolta automatica di dati personali. In self-hosting, tiene le vostre statistiche sul vostro server: decidete voi dove si trovano e per quanto tempo restano.

Tre impostazioni dello script di tracciamento vanno oltre, se lo desiderate: data-exclude-search toglie i parametri di ricerca dagli URL registrati, data-exclude-hash toglie l'hash, e data-do-not-track disattiva il tracciamento per i browser che espongono la preferenza Do Not Track. La documentazione precisa che quest'ultima impostazione non è, da sola, una soluzione completa di gestione del consenso.

Se identificate i visitatori connessi con data-distinct-id o umami.identify(), la documentazione raccomanda un ID utente interno o un hash anziché un indirizzo e-mail: il valore si legge nell'HTML della pagina.

L'installazione con Docker Compose e PostgreSQL

Il repository fornisce un docker-compose.yml che avvia Umami e il suo database PostgreSQL. Dalla versione 3, PostgreSQL è l'unico database supportato, almeno nella versione 12.14, e la documentazione raccomanda di impostarlo sul fuso orario UTC. Su un server in cui Docker è installato, create una cartella e cominciate dai segreti, generati in modo casuale con openssl, come suggerisce la documentazione:

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Collocate poi accanto questo compose.yaml. Segue il file del progetto alla versione 3.4.1, con due modifiche: i segreti arrivano dal file .env, e la porta è pubblicata solo su 127.0.0.1.

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

docker compose up -d
curl -s http://127.0.0.1:3000/api/heartbeat

• DATABASE_URL: l'unica variabile obbligatoria, la stringa di connessione al database. La password esadecimale si inserisce così com'è; una password con caratteri speciali richiederebbe la codifica percentuale.
• APP_SECRET: una stringa casuale che protegge i token di autenticazione, unica per ogni installazione. Nel codice della versione 3.4.1, entra anche nel calcolo degli ID di sessione: mantenetela stabile.
• TWO_FACTOR_ENCRYPTION_KEY: 64 caratteri esadecimali che cifrano i segreti dell'autenticazione a due fattori. Senza di essa, nessuno può attivare l'autenticazione a due fattori.
• All'avvio, il container verifica la connessione e la versione del database, poi applica da solo le migrazioni dello schema. Alla prima esecuzione, crea le tabelle e l'account admin. La sonda /api/heartbeat risponde {"ok":true} quando Umami è pronto.
• Il tag latest segue l'ultima versione pubblicata. Il registro del progetto pubblica anche tag di versione, come 3.4.1, per fissare quella che fate girare.

La documentazione di installazione non indica alcun valore di memoria o di CPU. La taglia dipende dal traffico dei siti seguiti e dal volume di dati che conservate. Su un VPS gestito, descrivetici il vostro uso e vi raccomandiamo la taglia adatta.

HTTPS: il reverse proxy

Umami ascolta in HTTP sulla porta 3000, e la documentazione suggerisce di servirlo dietro il vostro server web, tramite un reverse proxy. Dategli un sottodominio dedicato, come stats.example.com, che punta al server con record A e AAAA. Servire Umami in un percorso passa da BASE_PATH, una variabile letta alla compilazione dell'applicazione: con l'immagine pubblicata, il sottodominio è la strada diretta.

Il proxy deve anche trasmettere l'indirizzo del visitatore. Umami lo legge dalle intestazioni che riceve, tra cui X-Real-IP e X-Forwarded-For: lo usa per distinguere i visitatori e per localizzarne il paese. Se il vostro proxy usa un'altra intestazione, CLIENT_IP_HEADER la indica.

Con Caddy

Caddy ottiene il certificato Let's Encrypt e attiva HTTPS da solo. La sua direttiva reverse_proxy imposta X-Forwarded-For per impostazione predefinita: bastano queste tre righe.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Con Nginx e Certbot

Questo blocco segue l'esempio Nginx della documentazione di Umami, in ascolto sulla porta 80 per lasciare a Certbot l'attivazione di HTTPS:

server {
  listen 80;
  listen [::]:80;
  server_name stats.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Certbot installa poi il certificato e si occupa di rinnovarlo:

sudo certbot --nginx

Il primo accesso: l'account admin e l'autenticazione a due fattori

Quando crea il proprio database, Umami apre un account amministratore: nome utente admin, password umami. La documentazione chiede di cambiare questa password al primo accesso.

1. Aprite il vostro indirizzo HTTPS e accedete con admin e umami.
2. Aprite Settings dal pulsante del profilo nella barra laterale, poi Profile, e fate clic su Change password.
3. Nella scheda Security, attivate l'autenticazione a due fattori: scansionate il codice QR con la vostra app di autenticazione, inserite il codice a sei cifre, poi conservate in un luogo sicuro i dieci codici di emergenza, mostrati una sola volta.

• Imporre l'autenticazione a due fattori: un amministratore può richiederla per l'intera istanza, per un utente o per un team, dalle pagine di amministrazione.
• I tentativi: cinque codici errati bloccano i tentativi successivi per 15 minuti.
• Gli account del vostro team: le pagine di amministrazione gestiscono gli utenti, i siti e i team dell'intera istanza.

Conservate TWO_FACTOR_ENCRYPTION_KEY insieme ai vostri backup: la documentazione avverte che perdere o cambiare questa chiave rende illeggibili i segreti registrati, e ogni utente deve allora configurare di nuovo l'autenticazione a due fattori.

Aggiungere un sito e il suo script di tracciamento

1. In Websites, fate clic su Add website.
2. Date un nome al sito, poi il suo dominio: Umami lo usa per escludere le vostre stesse pagine dall'elenco dei siti di provenienza.
3. Aprite Edit su quel sito e copiate il codice della sezione Tracking code.
4. Incollatelo nel <head> delle vostre pagine, poi visitate il vostro sito: i dati compaiono subito nella dashboard.

<script defer src="https://stats.example.com/script.js" data-website-id="your-website-id"></script>

• Non compare nulla? La documentazione suggerisce la scheda rete degli strumenti per sviluppatori del browser: le richieste verso la vostra istanza devono partire senza errori.
• Next.js: aggiungete il codice con il componente next/script anziché con un semplice tag <script>.
• data-domains limita il tracciamento ai vostri domini di produzione, il che tiene i vostri ambienti di prova fuori dalle statistiche.
• Le vostre stesse visite si escludono sito per sito, dalla console del browser, con localStorage.setItem('umami.disabled', 1).

Uno script con un nome tutto vostro

Alcuni ad blocker bloccano tutto ciò che somiglia a uno strumento di analisi. In self-hosting, Umami è già servito dal vostro dominio, e due variabili vanno oltre: TRACKER_SCRIPT_NAME dà allo script un nome diverso da script.js, e COLLECT_API_ENDPOINT rinomina il punto di raccolta, al posto di /api/send. Lo script chiama poi da solo il nuovo punto; sulle vostre pagine cambia solo la sorgente del codice di tracciamento.

TRACKER_SCRIPT_NAME: "stats.js"
COLLECT_API_ENDPOINT: "/api/collect"

Le impostazioni utili

Queste variabili d'ambiente vanno nel servizio umami di compose.yaml, poi docker compose up -d ricrea il container perché vengano prese in considerazione:

I backup

Tutto ciò che Umami conserva vive nel suo database PostgreSQL: account, siti, team e statistiche. Esportatelo ogni giorno e subito prima di ogni aggiornamento: in self-hosting, questi dati si conservano senza limiti di tempo. Accanto al database, il file .env contiene i segreti che lo rendono utilizzabile:

Esportare il database in funzione

pg_dump produce un'esportazione coerente mentre il database è in uso. Il formato personalizzato, -Fc, è compresso e si ripristina con pg_restore:

docker compose exec -T db pg_dump -U umami -d umami -Fc > umami-$(date +%F).dump

Pianificate questo comando sul server almeno una volta al giorno, fate pulizia tra le esportazioni, che si accumulano, e inviatene una copia altrove. Conservate sul disco del server, queste esportazioni rientrano anche nei suoi backup notturni.

Ripristinare

1. Fermate Umami, lasciando in funzione il database: docker compose stop umami.
2. Ripristinate l'esportazione nel database, sostituendo gli oggetti esistenti.
3. Rilanciate Umami, poi verificate che i vostri siti e le loro statistiche ci siano.

docker compose stop umami
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists < umami-YYYY-MM-DD.dump
docker compose start umami

Ripetete questo esercizio di tanto in tanto, su una copia: è così che verificate che un backup funzioni.

Gli aggiornamenti

La documentazione fornisce due comandi, dalla cartella del compose.yaml. Il database resta nel suo volume:

docker compose pull
docker compose up --force-recreate -d

Al riavvio, il container applica da solo le migrazioni dello schema. La versione 3.4.0, del 17 settembre 2026, ne conteneva due, per le annotazioni e le chiavi API; la versione 3.4.1, del 23 ottobre 2026, non ne contiene. Dopo un aggiornamento importante, come il passaggio alla versione 3, la documentazione suggerisce di lanciare ANALYZE in PostgreSQL perché le dashboard ritrovino la loro velocità:

docker compose exec db psql -U umami -d umami -c "ANALYZE;"

• Le note di rilascio dicono che cosa cambia ogni versione. La versione 3.4.1 è una correzione di sicurezza che aggiorna Next.js e l'immagine di base Node.js; le sue note chiedono a ogni istanza self-hosted di aggiornare scaricando di nuovo l'immagine.
• Da una versione 2 su MySQL: la versione 3 non supporta più MySQL. La guida alla migrazione del progetto sposta i dati su PostgreSQL con la versione 2.19.0, prima del passaggio alla versione 3.
• PostgreSQL stesso: mantenete il tag postgres:15-alpine del file. Il passaggio a una nuova versione principale di PostgreSQL richiede un'esportazione e un ripristino, oppure pg_upgrade.

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; Umami resta il vostro software, con le sue impostazioni e i suoi dati.

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.