Găzduirea Umami pe un Managed VPS: statisticile web pe propriul server

Ce face Umami

Umami este o platformă open source de statistici web și de produs. Documentația sa descrie un instrument care reunește traficul, campaniile, comportamentul vizitatorilor, conversiile, retenția și veniturile, de la prima vizită până la rezultatele care contează pentru afacerea dumneavoastră. Este scris în TypeScript pe Next.js, iar imaginea sa Docker rulează sub un cont fără privilegii.

• Achiziția: afișări de pagini, vizitatori, surse de trafic, țări, dispozitive și activitate în timp real, cu campanii UTM, linkuri scurte și pixeli de urmărire.
• Comportamentul: evenimente personalizate, parcursuri, reluări de sesiuni, hărți termice, segmente, cohorte și retenție.
• Conversia: obiective, pâlnii, atribuire și urmărirea veniturilor pe pagină și pe campanie.
• Partajarea: panouri, echipe, un URL de partajare public, un API și un server MCP doar în citire pentru asistentul dumneavoastră AI.
• Site-urile moderne: FAQ-ul precizează că Umami urmărește singur navigarea între pagini în aplicațiile cu o singură pagină (SPA), fără nicio setare suplimentară.

O singură instanță urmărește mai multe site-uri: fiecare primește propriul ID și propriul script de urmărire, iar colegii dumneavoastră se orientează prin conturi și echipe.

Ce permite licența MIT

Umami este publicat sub licența MIT, în numele Umami Software, Inc. Ea acordă gratuit dreptul de a folosi, copia, modifica, fuziona, publica, distribui, sublicenția și vinde copii ale software-ului. Îl puteți deci rula pentru firma dumneavoastră și pentru site-urile clienților dumneavoastră, fără nicio licență de cumpărat.

Singura sa condiție: mențiunea de copyright și mențiunea de permisiune însoțesc toate copiile sau părțile substanțiale ale software-ului. Ca orice licență MIT, ea furnizează software-ul „ca atare” („as is”), fără garanție.

Cookie-urile și datele personale: ce spune proiectul

Documentația prezintă Umami ca un instrument de statistici fără cookie-uri, fără urmărire între site-uri și fără colectarea automată a datelor personale. Găzduit pe propriul server, el vă păstrează statisticile pe serverul dumneavoastră: decideți unde se află și cât timp rămân.

Trei setări ale scriptului de urmărire merg mai departe, dacă doriți: data-exclude-search elimină parametrii de căutare din URL-urile înregistrate, data-exclude-hash elimină fragmentul (hash), iar data-do-not-track oprește urmărirea pentru browserele care exprimă preferința Do Not Track. Documentația notează că această ultimă setare nu este, singură, o soluție completă de gestionare a consimțământului.

Dacă identificați vizitatorii conectați cu data-distinct-id sau umami.identify(), documentația recomandă un ID intern de utilizator sau un hash, mai degrabă decât o adresă de e-mail: valoarea poate fi citită în HTML-ul paginii.

Instalarea cu Docker Compose și PostgreSQL

Depozitul livrează un docker-compose.yml care pornește Umami și baza sa de date PostgreSQL. Începând cu versiunea 3, PostgreSQL este singura bază suportată, cel puțin în versiunea 12.14, iar documentația recomandă să o setați pe fusul orar UTC. Pe un server unde Docker este instalat, creați un director și începeți cu secretele, generate aleatoriu cu openssl, așa cum sugerează documentația:

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

Puneți apoi alături acest compose.yaml. El preia fișierul proiectului din versiunea 3.4.1, cu două modificări: secretele vin din fișierul .env, iar portul este publicat doar pe 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: singura variabilă obligatorie, șirul de conectare la baza de date. Parola hexazecimală se pune ca atare; o parolă cu caractere speciale ar cere codificare procentuală (percent-encoding).
• APP_SECRET: un șir aleatoriu care securizează tokenurile de autentificare, unic pentru fiecare instalare. În codul versiunii 3.4.1, el intră și în calculul ID-urilor de sesiune: păstrați-l stabil.
• TWO_FACTOR_ENCRYPTION_KEY: 64 de caractere hexazecimale care criptează secretele autentificării în doi pași. Fără ea, nimeni nu poate activa autentificarea în doi pași.
• La pornire, containerul verifică conexiunea și versiunea bazei de date, apoi aplică singur migrările de schemă. La prima rulare, creează tabelele și contul admin. Sonda /api/heartbeat răspunde {"ok":true} de îndată ce Umami este gata.
• Eticheta latest urmărește ultima versiune publicată. Registrul proiectului publică și etichete de versiune, precum 3.4.1, pentru a o fixa pe cea pe care o rulați.

Documentația de instalare nu indică nicio cifră pentru memorie sau procesor. Dimensiunea depinde de traficul site-urilor urmărite și de volumul datelor pe care le păstrați. Pe un Managed VPS, descrieți-ne utilizarea dumneavoastră și vă recomandăm dimensiunea potrivită.

HTTPS: proxy-ul invers

Umami ascultă în HTTP pe portul 3000, iar documentația sugerează să îl serviți în spatele serverului dumneavoastră web, printr-un proxy invers. Dați-i propriul subdomeniu, precum stats.example.com, care indică spre server prin înregistrări A și AAAA. Servirea Umami pe o cale trece prin BASE_PATH, o variabilă citită la construirea aplicației: cu imaginea publicată, subdomeniul este calea directă.

Proxy-ul trebuie să transmită și adresa vizitatorului. Umami o citește din antetele pe care le primește, printre care X-Real-IP și X-Forwarded-For: o folosește pentru a deosebi vizitatorii și pentru a le localiza țara. Dacă proxy-ul dumneavoastră folosește alt antet, CLIENT_IP_HEADER îl numește.

Cu Caddy

Caddy obține certificatul Let’s Encrypt și activează singur HTTPS. Directiva sa reverse_proxy setează implicit X-Forwarded-For: aceste trei linii sunt suficiente.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Cu Nginx și Certbot

Acest bloc preia exemplul Nginx din documentația Umami, ascultând pe portul 80, pentru a lăsa Certbot să instaleze 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 instalează apoi certificatul și se ocupă de reînnoirea lui:

sudo certbot --nginx

Prima conectare: contul de administrator și autentificarea în doi pași

Când își creează baza de date, Umami deschide un cont de administrator: numele de utilizator admin, parola umami. Documentația cere să schimbați această parolă la prima conectare.

1. Deschideți adresa dumneavoastră HTTPS și conectați-vă cu admin și umami.
2. Deschideți Settings din butonul de profil din bara laterală, apoi Profile, și faceți clic pe Change password.
3. În fila Security, activați autentificarea în doi pași: scanați codul QR cu aplicația dumneavoastră de autentificare, introduceți codul de șase cifre, apoi păstrați într-un loc sigur cele zece coduri de rezervă, care se afișează o singură dată.

• Impunerea autentificării în doi pași: un administrator o poate impune întregii instanțe, unui utilizator sau unei echipe, din paginile de administrare.
• Încercările: cinci coduri greșite blochează încercările următoare timp de 15 minute.
• Conturile echipei dumneavoastră: paginile de administrare gestionează utilizatorii, site-urile și echipele întregii instanțe.

Păstrați TWO_FACTOR_ENCRYPTION_KEY împreună cu backupurile dumneavoastră: documentația avertizează că pierderea sau schimbarea acestei chei face ilizibile secretele stocate, iar fiecare utilizator trebuie atunci să își configureze din nou autentificarea în doi pași.

Adăugarea unui site și a scriptului său de urmărire

1. În Websites, faceți clic pe Add website.
2. Dați site-ului un nume, apoi domeniul său: Umami îl folosește pentru a vă exclude propriile pagini din lista surselor de trafic.
3. Deschideți Edit pe acest site și copiați codul din secțiunea Tracking code.
4. Lipiți-l în <head>-ul paginilor dumneavoastră, apoi vizitați site-ul: datele apar imediat în tabloul de bord.

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

• Nu apare nimic? Documentația sugerează fila de rețea din instrumentele de dezvoltare ale browserului: cererile către instanța dumneavoastră trebuie să plece fără erori.
• Next.js: adăugați codul cu componenta next/script, mai degrabă decât cu o simplă etichetă <script>.
• data-domains limitează urmărirea la domeniile dumneavoastră de producție, ceea ce ține mediile de test în afara statisticilor.
• Propriile vizite se exclud site cu site, din consola browserului, cu localStorage.setItem('umami.disabled', 1).

Un nume de script propriu

Unele blocante de reclame blochează tot ce seamănă cu statisticile. Găzduit pe propriul server, Umami este deja servit de pe propriul domeniu, iar două variabile merg mai departe: TRACKER_SCRIPT_NAME dă scriptului alt nume decât script.js, iar COLLECT_API_ENDPOINT redenumește punctul de colectare, în locul lui /api/send. Scriptul apelează apoi singur noul punct; pe paginile dumneavoastră se schimbă doar sursa codului de urmărire.

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

Setările utile

Aceste variabile de mediu se pun în serviciul umami din compose.yaml, apoi docker compose up -d recreează containerul pentru a le lua în considerare:

Backupurile

Tot ce păstrează Umami se află în baza sa de date PostgreSQL: conturi, site-uri, echipe și statistici. Exportați-o în fiecare zi și chiar înaintea fiecărei actualizări: pe propriul server, aceste date sunt păstrate fără limită de timp. Pe lângă bază, fișierul .env conține secretele care o fac utilizabilă:

Exportul bazei în funcțiune

pg_dump face un export coerent în timp ce baza este folosită. Formatul personalizat, -Fc, este comprimat și se restaurează cu pg_restore:

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

Programați această comandă pe server cel puțin o dată pe zi, faceți ordine printre exporturi, care se acumulează, și trimiteți o copie în altă parte. Puse pe discul serverului, aceste exporturi intră și în backupurile sale de noapte.

Restaurarea

1. Opriți Umami, lăsând baza în funcțiune: docker compose stop umami.
2. Restaurați exportul în bază, înlocuind obiectele existente.
3. Reporniți Umami, apoi verificați că site-urile și statisticile lor sunt la locul lor.

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

Repetați acest exercițiu din când în când, pe o copie: așa verificați că un backup funcționează.

Actualizările

Documentația dă două comenzi, din directorul fișierului compose.yaml. Baza de date rămâne în volumul ei:

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

La repornire, containerul aplică singur migrările de schemă. Versiunea 3.4.0, din 17 septembrie 2026, aducea două, pentru adnotări și cheile API; versiunea 3.4.1, din 23 octombrie 2026, nu aduce niciuna. După o actualizare majoră, precum trecerea la versiunea 3, documentația sugerează rularea ANALYZE în PostgreSQL, pentru ca tablourile de bord să își recapete viteza:

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

• Notele de versiune spun ce schimbă fiecare versiune. Versiunea 3.4.1 este o corectură de securitate care actualizează Next.js și imaginea de bază Node.js; notele sale cer fiecărei instanțe găzduite pe propriul server să se actualizeze descărcând din nou imaginea.
• De la o versiune 2 pe MySQL: versiunea 3 nu mai suportă MySQL. Ghidul de migrare al proiectului mută datele în PostgreSQL pe versiunea 2.19.0, înainte de trecerea la versiunea 3.
• PostgreSQL însuși: păstrați eticheta postgres:15-alpine din fișier. Trecerea la o nouă versiune majoră de PostgreSQL cere un export și o restaurare sau pg_upgrade.

Cine ce face pe un Managed VPS

Găzduirea pe propriul server cere să țineți serverul pe lângă aplicație. Pe un Managed VPS, echipele noastre preiau serverul și vă urmăresc proactiv instanța; Umami rămâne software-ul dumneavoastră, cu setările și datele sale.

Dacă preferați ca echipele noastre să intervină în aplicația însăși, această prestație se facturează la oră sau la preț fix, cu o ofertă comunicată înainte de intervenție.