Hostovanie Umami na Managed VPS: vaša webová analytika na vašom serveri

Čo Umami robí

Umami je otvorená platforma na webovú a produktovú analytiku. Jeho dokumentácia opisuje nástroj, ktorý spája návštevnosť, kampane, správanie návštevníkov, konverzie, udržanie a tržby, od prvej návštevy po výsledky, na ktorých vašej firme záleží. Je napísaný v TypeScripte na Next.js a jeho obraz Docker beží pod neprivilegovaným účtom.

• Získavanie návštevníkov: zobrazenia stránok, návštevníci, odkazujúce weby, krajiny, zariadenia a aktivita v reálnom čase, s kampaňami UTM, skrátenými odkazmi a sledovacími pixelmi.
• Správanie: vlastné udalosti, cesty, záznamy relácií, teplotné mapy, segmenty, kohorty a udržanie.
• Konverzia: ciele, lieviky, atribúcia a sledovanie tržieb podľa stránky a podľa kampane.
• Zdieľanie: nástenky, tímy, verejná adresa na zdieľanie, API a server MCP len na čítanie pre vášho AI asistenta.
• Moderné weby: FAQ uvádza, že Umami sleduje navigáciu medzi stránkami v jednostránkových aplikáciách sám, bez ďalšieho nastavenia.

Jedna inštancia sleduje viacero webov: každý dostane vlastné ID a sledovací skript a vaši kolegovia sa v nich orientujú pomocou účtov a tímov.

Čo umožňuje licencia MIT

Umami vychádza pod licenciou MIT, v mene spoločnosti Umami Software, Inc. Bezplatne udeľuje právo používať, kopírovať, upravovať, zlučovať, zverejňovať, šíriť, poskytovať sublicencie a predávať kópie softvéru. Môžete ho teda prevádzkovať pre svoju firmu aj pre weby svojich klientov bez licencie, ktorú by ste museli kupovať.

Jej jediná podmienka: upozornenie o autorských právach a oznámenie o povolení sprevádzajú všetky kópie alebo podstatné časti softvéru. Ako každá licencia MIT poskytuje softvér „tak, ako je“, bez záruky.

Cookies a osobné údaje: čo uvádza projekt

Dokumentácia predstavuje Umami ako analytiku bez cookies, bez sledovania naprieč webmi a bez automatického zberu osobných údajov. Pri vlastnej prevádzke zostáva vaša analytika na vašom serveri: rozhodujete, kde sa uchováva a ako dlho.

Tri nastavenia sledovacieho skriptu idú, ak chcete, ďalej: data-exclude-search odstraňuje parametre vyhľadávania zo zaznamenaných adries, data-exclude-hash odstraňuje časť za znakom mriežky a data-do-not-track vypína sledovanie pre prehliadače, ktoré zverejňujú preferenciu Do Not Track. Dokumentácia poznamenáva, že toto posledné nastavenie samo osebe nie je úplným riešením správy súhlasu.

Ak identifikujete prihlásených návštevníkov pomocou data-distinct-id alebo umami.identify(), dokumentácia odporúča interné ID používateľa alebo haš namiesto e-mailovej adresy: hodnotu možno prečítať v HTML stránky.

Inštalácia pomocou Docker Compose a PostgreSQL

Repozitár obsahuje súbor docker-compose.yml, ktorý spustí Umami a jeho databázu PostgreSQL. Od verzie 3 je PostgreSQL jedinou podporovanou databázou, minimálne vo verzii 12.14, a dokumentácia odporúča nastaviť ju na časové pásmo UTC. Na serveri s nainštalovaným Dockerom vytvorte priečinok a začnite jeho tajnými údajmi, náhodne vygenerovanými cez openssl, ako navrhuje dokumentácia:

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

Potom vedľa neho umiestnite tento súbor compose.yaml. Vychádza zo súboru projektu vo verzii 3.4.1 s dvoma zmenami: tajné údaje pochádzajú zo súboru .env a port je publikovaný len na 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: jediná povinná premenná, reťazec pripojenia k databáze. Hexadecimálne heslo sa vkladá tak, ako je; heslo so špeciálnymi znakmi by si vyžadovalo percentuálne kódovanie.
• APP_SECRET: náhodný reťazec, ktorý zabezpečuje overovacie tokeny, jedinečný pre každú inštaláciu. V kóde verzie 3.4.1 vstupuje aj do výpočtu ID relácií: udržujte ho nemenný.
• TWO_FACTOR_ENCRYPTION_KEY: 64 hexadecimálnych znakov, ktoré šifrujú tajné údaje dvojfaktorového overenia. Bez neho si dvojfaktorové overenie nemôže zapnúť nikto.
• Pri štarte kontajner overí pripojenie k databáze a jej verziu a potom sám použije migrácie schémy. Pri prvom spustení vytvorí tabuľky a účet admin. Sonda /api/heartbeat odpovie {"ok":true}, keď je Umami pripravený.
• Značka latest sleduje posledné zverejnené vydanie. Register projektu zverejňuje aj značky verzií, napríklad 3.4.1, na pripnutie tej, ktorú prevádzkujete.

Inštalačná dokumentácia neuvádza nároky na pamäť ani procesor. Veľkosť závisí od návštevnosti sledovaných webov a od objemu údajov, ktoré uchovávate. Na spravovanom VPS (Managed VPS) nám opíšte svoje použitie a odporučíme vám vhodnú veľkosť.

HTTPS: reverzná proxy

Umami počúva cez HTTP na porte 3000 a dokumentácia navrhuje obsluhovať ho za vaším webovým serverom, cez reverznú proxy. Dajte mu vlastnú subdoménu, napríklad stats.example.com, nasmerovanú na server záznamami A a AAAA. Obsluha Umami pod cestou prechádza cez BASE_PATH, premennú načítanú pri zostavení aplikácie: so zverejneným obrazom je subdoména priamou cestou.

Proxy musí odovzdať aj adresu návštevníka. Umami ju číta z hlavičiek, ktoré dostáva, vrátane X-Real-IP a X-Forwarded-For: používa ju na rozlíšenie návštevníkov a určenie ich krajiny. Ak vaša proxy používa inú hlavičku, pomenuje ju CLIENT_IP_HEADER.

S Caddy

Caddy získa certifikát Let’s Encrypt a zapne HTTPS sám. Jeho direktíva reverse_proxy predvolene nastavuje X-Forwarded-For: tieto tri riadky sú všetko, čo potrebujete.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

S Nginx a Certbotom

Tento blok preberá príklad Nginx z dokumentácie Umami, s počúvaním na porte 80, aby HTTPS mohol zapnúť Certbot:

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 potom nainštaluje certifikát a postará sa o jeho obnovu:

sudo certbot --nginx

Prvé prihlásenie: účet admin a dvojfaktorové overenie

Pri vytvorení svojej databázy otvorí Umami účet správcu: používateľské meno admin, heslo umami. Dokumentácia žiada toto heslo zmeniť pri prvom prihlásení.

1. Otvorte svoju adresu HTTPS a prihláste sa pomocou admin a umami.
2. Tlačidlom profilu v bočnom paneli otvorte Settings, potom Profile, a kliknite na Change password.
3. Na karte Security zapnite dvojfaktorové overenie: naskenujte QR kód svojou autentifikačnou aplikáciou, zadajte šesťmiestny kód a potom uložte desať záložných kódov na bezpečné miesto, pretože sa zobrazia len raz.

• Vyžadovanie dvojfaktorového overenia: správca ho môže vyžadovať pre celú inštanciu, pre jedného používateľa alebo pre jeden tím, zo stránok administrácie.
• Pokusy: päť nesprávnych kódov zablokuje ďalšie pokusy na 15 minút.
• Účty vášho tímu: stránky administrácie spravujú používateľov, weby a tímy celej inštancie.

Uchovávajte TWO_FACTOR_ENCRYPTION_KEY spolu so svojimi zálohami: dokumentácia upozorňuje, že strata alebo zmena tohto kľúča spôsobí, že uložené tajné údaje budú nečitateľné, a každý používateľ si potom musí dvojfaktorové overenie nastaviť znova.

Pridanie webu a jeho sledovacieho skriptu

1. V časti Websites kliknite na Add website.
2. Zadajte názov webu a potom jeho doménu: Umami ju používa na vyradenie vašich vlastných stránok zo zoznamu odkazujúcich webov.
3. Pri tomto webe otvorte Edit a skopírujte kód z časti Tracking code.
4. Vložte ho do <head> svojich stránok a potom navštívte svoj web: údaje sa v prehľade objavia okamžite.

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

• Nič sa nezobrazuje? Dokumentácia navrhuje kartu sieť vo vývojárskych nástrojoch prehliadača: požiadavky na vašu inštanciu by mali odchádzať bez chýb.
• Next.js: kód pridajte komponentom next/script namiesto obyčajnej značky <script>.
• data-domains obmedzuje sledovanie na vaše produkčné domény, čím vaše testovacie prostredia zostanú mimo štatistík.
• Vaše vlastné návštevy vylúčite web po webe z konzoly prehliadača príkazom localStorage.setItem('umami.disabled', 1).

Vlastný názov skriptu

Niektoré blokovače reklám blokujú všetko, čo pripomína analytiku. Pri vlastnej prevádzke sa Umami už obsluhuje z vašej vlastnej domény a dve premenné idú ďalej: TRACKER_SCRIPT_NAME dáva skriptu iný názov než script.js a COLLECT_API_ENDPOINT premenuje koncový bod zberu namiesto /api/send. Skript potom volá nový koncový bod sám; na vašich stránkach sa mení len zdroj sledovacieho kódu.

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

Užitočné nastavenia

Tieto premenné prostredia patria do služby umami v súbore compose.yaml a docker compose up -d potom kontajner znova vytvorí, aby ich zohľadnil:

Zálohy

Všetko, čo Umami uchováva, je v jeho databáze PostgreSQL: účty, weby, tímy a analytika. Exportujte ju každý deň a tesne pred každou aktualizáciou: pri vlastnej prevádzke sa tieto údaje uchovávajú bez časového obmedzenia. Popri databáze obsahuje súbor .env tajné údaje, vďaka ktorým je použiteľná:

Export databázy počas prevádzky

pg_dump vytvorí konzistentný export, aj keď sa databáza používa. Vlastný formát, -Fc, je komprimovaný a obnovuje sa pomocou pg_restore:

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

Tento príkaz naplánujte na serveri aspoň raz denne, exporty, ktoré sa hromadia, prebierajte a kópiu posielajte inam. Uložené na disku servera sa tieto exporty dostanú aj do jeho nočných záloh.

Obnova

1. Zastavte Umami a databázu nechajte bežať: docker compose stop umami.
2. Obnovte export do databázy s nahradením existujúcich objektov.
3. Znova spustite Umami a overte, že vaše weby a ich analytika sú na mieste.

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

Toto cvičenie z času na čas zopakujte na kópii: takto overíte, že záloha funguje.

Aktualizácie

Dokumentácia uvádza dva príkazy, spúšťané z priečinka so súborom compose.yaml. Databáza zostáva vo svojom zväzku:

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

Pri reštarte kontajner sám použije migrácie schémy. Verzia 3.4.0 zo 17. septembra 2026 ich priniesla dve, pre anotácie a kľúče API; verzia 3.4.1 z 23. októbra 2026 žiadnu. Po veľkej aktualizácii, napríklad pri prechode na verziu 3, dokumentácia navrhuje spustiť v PostgreSQL ANALYZE, aby prehľady znova získali svoju rýchlosť:

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

• Poznámky k vydaniu uvádzajú, čo každá verzia mení. Verzia 3.4.1 je rýchla bezpečnostná oprava, ktorá aktualizuje Next.js a základný obraz Node.js; jej poznámky žiadajú každú inštanciu vo vlastnej prevádzke aktualizovať opätovným stiahnutím obrazu.
• Z verzie 2 na MySQL: verzia 3 už MySQL nepodporuje. Migračná príručka projektu presúva údaje do PostgreSQL vo verzii 2.19.0, pred aktualizáciou na verziu 3.
• Samotný PostgreSQL: ponechajte značku postgres:15-alpine zo súboru. Prechod na novú hlavnú verziu PostgreSQL vyžaduje export a obnovu, alebo pg_upgrade.

Kto čo robí na Managed VPS

Hostovanie na vlastnom serveri vyžaduje popri aplikácii starať sa aj o server. Na Managed VPS preberajú server naše tímy a vašu inštanciu proaktívne sledujú; Umami zostáva vaším softvérom, s vašimi nastaveniami a údajmi.

Ak by ste uprednostnili, aby naše tímy zasiahli priamo v aplikácii, táto služba sa fakturuje hodinovo alebo paušálne, s cenovou ponukou oznámenou pred zásahom.