Umami hosztolása Managed VPS-en: webanalitikája a saját szerverén

Mit tud az Umami

Az Umami nyílt forráskódú web- és termékanalitikai platform. A dokumentációja olyan eszközt ír le, amely egy helyen gyűjti össze a forgalmat, a kampányokat, a látogatói viselkedést, a konverziókat, a megtartást és a bevételeket, az első látogatástól a vállalkozása számára fontos eredményekig. TypeScriptben, Next.js-re épülve készült, a Docker image-e pedig jogosultságok nélküli fiókkal fut.

• Az ügyfélszerzés: oldalmegtekintések, látogatók, hivatkozó oldalak, országok, eszközök és valós idejű aktivitás, UTM-kampányokkal, rövid linkekkel és követőpixelekkel.
• A viselkedés: egyéni események, látogatói utak, munkamenet-visszajátszások, hőtérképek, szegmensek, kohorszok és megtartás.
• A konverzió: célok, tölcsérek, hozzárendelés és a bevételek követése oldalanként és kampányonként.
• A megosztás: táblák, csapatok, nyilvános megosztási URL, API és egy csak olvasható MCP-szerver az MI-asszisztense számára.
• A modern weboldalak: a GYIK kimondja, hogy az Umami az egyoldalas alkalmazásokban magától követi az oldalak közötti navigációt, külön beállítás nélkül.

Egy példány több weboldalt követ: mindegyik saját azonosítót és saját követőkódot kap, a kollégái pedig a fiókoknak és a csapatoknak köszönhetően igazodnak el.

Mit enged meg az MIT licenc

Az Umami az MIT licenc alatt jelenik meg, az Umami Software, Inc. nevében. Ez ingyenesen biztosítja a szoftver használatának, másolásának, módosításának, egyesítésének, közzétételének, terjesztésének, allicencbe adásának és másolatai értékesítésének jogát. Futtathatja tehát a vállalkozásához és az ügyfelei weboldalaihoz, licenc vásárlása nélkül.

Egyetlen feltétele: a szerzői jogi megjegyzés és az engedélyről szóló megjegyzés kíséri a szoftver minden másolatát vagy lényeges részét. Mint minden MIT licenc, a szoftvert „ahogy van” állapotban, garancia nélkül adja.

Sütik és személyes adatok: amit a projekt mond

A dokumentáció az Umamit sütik nélküli analitikaként mutatja be, webhelyek közötti követés és a személyes adatok automatikus gyűjtése nélkül. Saját üzemeltetésben a statisztikái a saját szerverén maradnak: Ön dönti el, hol vannak, és mennyi ideig maradnak meg.

Ha szeretné, a követőkód három beállításával tovább mehet: a data-exclude-search eltávolítja a keresési paramétereket a rögzített URL-ekből, a data-exclude-hash eltávolítja a hash-részt, a data-do-not-track pedig kikapcsolja a követést azokban a böngészőkben, amelyek jelzik a Do Not Track beállítást. A dokumentáció megjegyzi, hogy ez utóbbi beállítás önmagában nem teljes hozzájáruláskezelési megoldás.

Ha a bejelentkezett látogatókat a data-distinct-id vagy az umami.identify() segítségével azonosítja, a dokumentáció e-mail-cím helyett belső felhasználói azonosítót vagy hash-értéket ajánl: az érték kiolvasható az oldal HTML-kódjából.

Telepítés Docker Compose-zal és PostgreSQL-lel

A tároló egy docker-compose.yml fájlt ad, amely elindítja az Umamit és a PostgreSQL-adatbázisát. A 3-as verzió óta a PostgreSQL az egyetlen támogatott adatbázis, legalább a 12.14-es verzióban, és a dokumentáció UTC időzónára állítását ajánlja. Egy olyan szerveren, ahol a Docker telepítve van, hozzon létre egy mappát, és kezdje a titkos kulcsaival, amelyeket a dokumentáció javaslatára az openssl segítségével véletlenszerűen állít elő:

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

Ezután helyezze mellé ezt a compose.yaml fájlt. A projekt 3.4.1-es verziójú fájlját követi, két módosítással: a titkos kulcsok az .env fájlból érkeznek, a port pedig csak a 127.0.0.1 címen van közzétéve.

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

• A DATABASE_URL: az egyetlen kötelező változó, az adatbázis kapcsolati karakterlánca. A hexadecimális jelszó változtatás nélkül kerül bele; a speciális karaktereket tartalmazó jelszót százalékkódolással kellene írni.
• Az APP_SECRET: véletlenszerű karakterlánc, amely a hitelesítési tokeneket védi, és minden telepítésnél egyedi. A 3.4.1-es verzió kódjában a munkamenet-azonosítók kiszámításában is részt vesz: tartsa állandóan.
• A TWO_FACTOR_ENCRYPTION_KEY: 64 hexadecimális karakter, amely a kétlépcsős hitelesítés titkait titkosítja. Nélküle senki sem kapcsolhatja be a kétlépcsős hitelesítést.
• Indításkor a konténer ellenőrzi az adatbázis-kapcsolatot és a verziót, majd maga alkalmazza a sémamigrációkat. Az első indításkor létrehozza a táblákat és az admin fiókot. A /api/heartbeat végpont {"ok":true} választ ad, amint az Umami készen áll.
• A latest címke a legutóbb közzétett kiadást követi. A projekt image-tárhelye verziócímkéket is közzétesz, például 3.4.1, hogy rögzíthesse a futtatott verziót.

A telepítési dokumentáció nem ad meg memória- és processzorigényt. A méret a követett weboldalak forgalmától és a megőrzött adatok mennyiségétől függ. Egy Managed VPS esetén írja le nekünk a használatát, és mi azt a méretet javasoljuk, amely megfelel.

HTTPS: a fordított proxy

Az Umami HTTP-n, a 3000-es porton figyel, és a dokumentáció azt javasolja, hogy a webszervere mögött, fordított proxyn keresztül szolgálja ki. Adjon neki saját aldomaint, például stats.example.com, amely A és AAAA rekordokkal a szerverre mutat. Az Umami egy útvonal alatti kiszolgálása a BASE_PATH változón keresztül történik, amelyet az alkalmazás felépítésekor olvas be: a közzétett image-gel az aldomain a közvetlen út.

A proxynak a látogató címét is tovább kell adnia. Az Umami a kapott fejlécekből olvassa ki, köztük az X-Real-IP és az X-Forwarded-For fejlécből: ennek segítségével különbözteti meg a látogatókat, és határozza meg az országukat. Ha a proxyja más fejlécet használ, a CLIENT_IP_HEADER nevezi meg.

Caddyvel

A Caddy magától megszerzi a Let's Encrypt-tanúsítványt és bekapcsolja a HTTPS-t. A reverse_proxy direktívája alapértelmezésként beállítja az X-Forwarded-For fejlécet: ez a három sor minden, amire szüksége van.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Nginxszel és Certbottal

Ez a blokk az Umami dokumentációjának Nginx-példáját követi, a 80-as porton figyelve, hogy a Certbot beállíthassa a HTTPS-t:

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;
  }
}

A Certbot ezután telepíti a tanúsítványt, és gondoskodik a megújításáról:

sudo certbot --nginx

Az első bejelentkezés: az adminisztrátori fiók és a kétlépcsős hitelesítés

Az adatbázis létrehozásakor az Umami adminisztrátori fiókot nyit: a felhasználónév admin, a jelszó umami. A dokumentáció azt kéri, hogy ezt a jelszót az első bejelentkezéskor módosítsa.

1. Nyissa meg a HTTPS-címét, és jelentkezzen be az admin és az umami adatokkal.
2. Nyissa meg a Settings (Beállítások) oldalt az oldalsáv profilgombjáról, majd a Profile (Profil) részt, és kattintson a Change password (Jelszó módosítása) gombra.
3. A Security (Biztonság) lapon kapcsolja be a kétlépcsős hitelesítést: olvassa be a QR-kódot a hitelesítő alkalmazásával, adja meg a hatjegyű kódot, majd őrizze biztonságos helyen a tíz tartalékkódot, mert csak egyszer jelennek meg.

• A kétlépcsős hitelesítés előírása: egy adminisztrátor az adminisztrációs oldalakról előírhatja a teljes példányra, egy felhasználóra vagy egy csapatra.
• A próbálkozások: öt hibás kód után 15 percre letiltódnak a további próbálkozások.
• A csapata fiókjai: az adminisztrációs oldalak a teljes példány felhasználóit, weboldalait és csapatait kezelik.

Őrizze a TWO_FACTOR_ENCRYPTION_KEY kulcsot a mentései mellett: a dokumentáció figyelmeztet, hogy ennek a kulcsnak az elvesztése vagy cseréje olvashatatlanná teszi a tárolt titkokat, és ekkor minden felhasználónak újra be kell állítania a kétlépcsős hitelesítést.

Weboldal és követőkód hozzáadása

1. A Websites (Weboldalak) részben kattintson az Add website (Weboldal hozzáadása) gombra.
2. Adjon nevet a weboldalnak, majd adja meg a domainjét: az Umami ennek alapján szűri ki a saját oldalait a hivatkozó oldalak listájából.
3. Nyissa meg az Edit (Szerkesztés) lehetőséget ennél a weboldalnál, és másolja ki a kódot a Tracking code (Követőkód) részből.
4. Illessze be az oldalai <head> részébe, majd látogasson el a weboldalára: az adatok azonnal megjelennek az irányítópulton.

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

• Nem jelenik meg semmi? A dokumentáció a böngésző fejlesztői eszközeinek hálózat lapját javasolja: a példánya felé menő kéréseknek hiba nélkül kell elindulniuk.
• Next.js: a kódot a next/script komponenssel adja hozzá, ne egy egyszerű <script> címkével.
• A data-domains az éles domainjeire korlátozza a követést, így a tesztkörnyezetei kimaradnak a statisztikákból.
• A saját látogatásai weboldalanként zárhatók ki, a böngészőkonzolból, a localStorage.setItem('umami.disabled', 1) paranccsal.

Saját szkriptnév

Egyes reklámblokkolók mindent blokkolnak, ami analitikának tűnik. Saját üzemeltetésben az Umamit már a saját domainjéről szolgálja ki, és két változóval tovább mehet: a TRACKER_SCRIPT_NAME a script.js helyett más nevet ad a szkriptnek, a COLLECT_API_ENDPOINT pedig a /api/send helyett más nevet ad az adatgyűjtő végpontnak. A szkript ezután magától az új végpontot hívja; az oldalain csak a követőkód forrása változik.

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

Hasznos beállítások

Ezek a környezeti változók a compose.yaml fájl umami szolgáltatásába kerülnek, majd a docker compose up -d újra létrehozza a konténert, hogy érvénybe lépjenek:

A mentések

Mindaz, amit az Umami megőriz, a PostgreSQL-adatbázisában él: fiókok, weboldalak, csapatok és statisztikák. Exportálja naponta és közvetlenül minden frissítés előtt: saját üzemeltetésben ezek az adatok időkorlát nélkül megmaradnak. Az adatbázis mellett az .env fájl tartalmazza azokat a titkos kulcsokat, amelyek használhatóvá teszik:

Az adatbázis exportálása futás közben

A pg_dump konzisztens exportot készít, miközben az adatbázis használatban van. Az egyéni formátum, a -Fc, tömörített, és a pg_restore paranccsal állítható vissza:

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

Ütemezze ezt a parancsot a szerveren legalább naponta egyszer, válogassa ki az exportokat, mert felhalmozódnak, és küldjön egy másolatot máshová. A szerver lemezén tartva ezek az exportok a szerver éjszakai mentéseibe is bekerülnek.

Visszaállítás

1. Állítsa le az Umamit, az adatbázist futni hagyva: docker compose stop umami.
2. Állítsa vissza az exportot az adatbázisba, a meglévő objektumokat lecserélve.
3. Indítsa újra az Umamit, majd ellenőrizze, hogy a weboldalai és a statisztikáik megvannak-e.

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

Ismételje meg ezt a gyakorlatot időnként, egy másolaton: így győződhet meg róla, hogy egy mentés működik.

A frissítések

A dokumentáció két parancsot ad meg, a compose.yaml mappájából. Az adatbázis a kötetében marad:

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

Újraindításkor a konténer maga alkalmazza a sémamigrációkat. A 2026. szeptember 17-i 3.4.0-s verzió kettőt hozott, a megjegyzésekhez és az API-kulcsokhoz; a 2026. október 23-i 3.4.1-es verzió egyet sem. Egy nagyobb frissítés után, mint a 3-as verzióra való átállás, a dokumentáció azt javasolja, hogy futtassa az ANALYZE parancsot a PostgreSQL-ben, hogy az irányítópultok visszanyerjék a sebességüket:

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

• A kiadási megjegyzések leírják, mit változtat egy-egy verzió. A 3.4.1-es verzió biztonsági gyorsjavítás, amely frissíti a Next.js-t és a Node.js alap-image-et; a megjegyzései minden saját üzemeltetésű példányt arra kérnek, hogy az image újbóli letöltésével frissítsen.
• MySQL-en futó 2-es verzióról: a 3-as verzió már nem támogatja a MySQL-t. A projekt áttérési útmutatója a 2.19.0-s verzión viszi át az adatokat PostgreSQL-re, a 3-as verzióra való frissítés előtt.
• Maga a PostgreSQL: tartsa meg a fájl postgres:15-alpine címkéjét. A PostgreSQL új főverziójára való áttéréshez export és visszaállítás, vagy a pg_upgrade szükséges.

Ki mit csinál egy Managed VPS-en

A saját üzemeltetés az alkalmazás mellett a szerver gondozását is megköveteli. Egy Managed VPS esetén csapataink átveszik a szervert, és proaktívan követik a példányát; az Umami továbbra is az Ön szoftvere marad, a beállításaival és az adataival.

Ha inkább azt szeretné, hogy csapataink magában az alkalmazásban avatkozzanak be, ez a szolgáltatás óradíjban vagy átalánydíjban számlázódik, a beavatkozás előtt közölt árajánlattal.