Hosting Umami na Managed VPS: Państwa statystyki witryn na Państwa serwerze

Co robi Umami

Umami to otwartoźródłowa platforma analityki internetowej i produktowej. Dokumentacja opisuje narzędzie, które łączy ruch, kampanie, zachowanie odwiedzających, konwersje, retencję i przychody, od pierwszej wizyty po wyniki ważne dla Państwa działalności. Jest napisany w TypeScripcie na Next.js, a jego obraz Docker działa na koncie bez uprawnień administratora.

• Pozyskiwanie: odsłony, odwiedzający, strony odsyłające, kraje, urządzenia i aktywność w czasie rzeczywistym, z kampaniami UTM, krótkimi linkami i pikselami śledzącymi.
• Zachowanie: własne zdarzenia, ścieżki, nagrania sesji, mapy cieplne, segmenty, kohorty i retencja.
• Konwersja: cele, lejki, atrybucja i śledzenie przychodów według stron i kampanii.
• Udostępnianie: tablice, zespoły, publiczny adres udostępniania, API i serwer MCP tylko do odczytu dla Państwa asystenta AI.
• Nowoczesne witryny: FAQ podaje, że Umami sam śledzi nawigację między stronami w aplikacjach jednostronicowych, bez dodatkowych ustawień.

Jedna instancja śledzi kilka witryn: każda otrzymuje własny identyfikator i skrypt śledzący, a współpracownicy odnajdują się w niej dzięki kontom i zespołom.

Na co pozwala licencja MIT

Umami jest udostępniany na licencji MIT, w imieniu Umami Software, Inc. Przyznaje ona bezpłatnie prawo do używania, kopiowania, modyfikowania, łączenia, publikowania, rozpowszechniania, sublicencjonowania i sprzedawania kopii oprogramowania. Mogą więc Państwo uruchomić go dla swojej firmy i dla witryn swoich klientów, bez zakupu licencji.

Jej jedyny warunek: informacja o prawach autorskich i informacja o zezwoleniu towarzyszą wszystkim kopiom lub istotnym częściom oprogramowania. Jak każda licencja MIT, dostarcza ona oprogramowanie „w stanie, w jakim jest”, bez gwarancji.

Pliki cookie i dane osobowe: co mówi projekt

Dokumentacja przedstawia Umami jako analitykę bez plików cookie, bez śledzenia między witrynami i bez automatycznego zbierania danych osobowych. Hostowany samodzielnie, utrzymuje Państwa statystyki na Państwa własnym serwerze: to Państwo decydują, gdzie się znajdują i jak długo są przechowywane.

Trzy ustawienia skryptu śledzącego idą dalej, jeśli Państwo sobie tego życzą: data-exclude-search usuwa parametry wyszukiwania z zapisywanych adresów, data-exclude-hash usuwa fragment po krzyżyku, a data-do-not-track wyłącza śledzenie w przeglądarkach, które udostępniają preferencję Do Not Track. Dokumentacja zaznacza, że to ostatnie ustawienie samo w sobie nie jest pełnym rozwiązaniem do zarządzania zgodami.

Jeśli identyfikują Państwo zalogowanych odwiedzających przez data-distinct-id lub umami.identify(), dokumentacja zaleca wewnętrzny identyfikator użytkownika lub skrót zamiast adresu e-mail: wartość tę można odczytać w kodzie HTML strony.

Instalacja przez Docker Compose i PostgreSQL

Repozytorium dostarcza docker-compose.yml, który uruchamia Umami i jego bazę PostgreSQL. Od wersji 3 PostgreSQL jest jedyną obsługiwaną bazą, co najmniej w wersji 12.14, a dokumentacja zaleca ustawienie w niej strefy czasowej UTC. Na serwerze z zainstalowanym Dockerem proszę utworzyć katalog i zacząć od sekretów, generowanych losowo przez openssl, jak proponuje dokumentacja:

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

Następnie proszę umieścić obok ten compose.yaml. Podąża on za plikiem projektu w wersji 3.4.1, z dwiema zmianami: sekrety pochodzą z pliku .env, a port jest publikowany wyłącznie 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: jedyna wymagana zmienna, ciąg połączenia z bazą. Hasło szesnastkowe wpisuje się bez zmian; hasło ze znakami specjalnymi wymagałoby kodowania procentowego.
• APP_SECRET: losowy ciąg, który zabezpiecza tokeny uwierzytelniania, unikalny dla każdej instalacji. W kodzie wersji 3.4.1 wchodzi też do obliczania identyfikatorów sesji: proszę go nie zmieniać.
• TWO_FACTOR_ENCRYPTION_KEY: 64 znaki szesnastkowe, które szyfrują sekrety uwierzytelniania dwuskładnikowego. Bez tego klucza nikt nie może włączyć uwierzytelniania dwuskładnikowego.
• Przy starcie kontener sprawdza połączenie z bazą i jej wersję, a następnie sam stosuje migracje schematu. Przy pierwszym uruchomieniu tworzy tabele i konto admin. Sonda /api/heartbeat odpowiada {"ok":true}, gdy Umami jest gotowy.
• Tag latest podąża za ostatnią opublikowaną wersją. Rejestr projektu publikuje też tagi wersji, takie jak 3.4.1, aby przypiąć tę, której Państwo używają.

Dokumentacja instalacji nie podaje wymagań dotyczących pamięci ani procesora. Rozmiar zależy od ruchu śledzonych witryn i od ilości przechowywanych danych. Na Managed VPS wystarczy opisać nam swoje zastosowanie, a polecimy odpowiedni rozmiar.

HTTPS: odwrotne proxy

Umami nasłuchuje przez HTTP na porcie 3000, a dokumentacja proponuje udostępnić go za Państwa serwerem WWW, przez odwrotne proxy. Proszę nadać mu własną subdomenę, taką jak stats.example.com, wskazującą na serwer rekordami A i AAAA. Udostępnienie Umami pod ścieżką wymaga BASE_PATH, zmiennej odczytywanej podczas budowania aplikacji: przy opublikowanym obrazie subdomena jest drogą najprostszą.

Proxy musi też przekazywać adres odwiedzającego. Umami odczytuje go z otrzymanych nagłówków, w tym X-Real-IP i X-Forwarded-For: służy mu on do rozróżniania odwiedzających i ustalania ich kraju. Jeśli Państwa proxy używa innego nagłówka, wskazuje go CLIENT_IP_HEADER.

Z Caddy

Caddy sam uzyskuje certyfikat Let’s Encrypt i włącza HTTPS. Jego dyrektywa reverse_proxy domyślnie ustawia X-Forwarded-For: te trzy wiersze w zupełności wystarczą.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Z Nginx i Certbotem

Ten blok podąża za przykładem Nginx z dokumentacji Umami i nasłuchuje na porcie 80, aby Certbot mógł zainstalować 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 następnie instaluje certyfikat i zajmuje się jego odnawianiem:

sudo certbot --nginx

Pierwsze logowanie: konto administratora i uwierzytelnianie dwuskładnikowe

Tworząc swoją bazę, Umami zakłada konto administratora: nazwa użytkownika admin, hasło umami. Dokumentacja prosi o zmianę tego hasła przy pierwszym logowaniu.

1. Proszę otworzyć swój adres HTTPS i zalogować się danymi admin i umami.
2. Proszę otworzyć Settings przyciskiem profilu na pasku bocznym, następnie Profile, i kliknąć Change password.
3. W zakładce Security proszę włączyć uwierzytelnianie dwuskładnikowe: zeskanować kod QR aplikacją uwierzytelniającą, wpisać sześciocyfrowy kod, a następnie zachować w bezpiecznym miejscu dziesięć kodów zapasowych, wyświetlanych tylko raz.

• Wymaganie uwierzytelniania dwuskładnikowego: administrator może go wymagać dla całej instancji, dla jednego użytkownika lub dla jednego zespołu, ze stron administracyjnych.
• Próby: pięć błędnych kodów blokuje kolejne próby na 15 minut.
• Konta Państwa zespołu: strony administracyjne zarządzają użytkownikami, witrynami i zespołami całej instancji.

Proszę przechowywać TWO_FACTOR_ENCRYPTION_KEY razem z kopiami zapasowymi: dokumentacja ostrzega, że utrata lub zmiana tego klucza sprawia, że zapisane sekrety stają się nieczytelne, a każdy użytkownik musi wtedy ponownie skonfigurować uwierzytelnianie dwuskładnikowe.

Dodanie witryny i jej skryptu śledzącego

1. W Websites proszę kliknąć Add website.
2. Proszę nadać witrynie nazwę, a następnie podać jej domenę: Umami używa jej, by usuwać Państwa własne strony z listy stron odsyłających.
3. Proszę otworzyć Edit przy tej witrynie i skopiować kod z sekcji Tracking code.
4. Proszę wkleić go do sekcji <head> swoich stron, a następnie odwiedzić swoją witrynę: dane od razu pojawiają się w panelu.

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

• Nic się nie pojawia? Dokumentacja proponuje zakładkę sieci w narzędziach deweloperskich przeglądarki: żądania do Państwa instancji powinny wychodzić bez błędów.
• Next.js: proszę dodać kod komponentem next/script zamiast zwykłego znacznika <script>.
• data-domains ogranicza śledzenie do domen produkcyjnych, co utrzymuje środowiska testowe poza statystykami.
• Własne wizyty wyklucza się witryna po witrynie, z konsoli przeglądarki, poleceniem localStorage.setItem('umami.disabled', 1).

Własna nazwa skryptu

Niektóre programy blokujące reklamy blokują wszystko, co przypomina analitykę. Przy samodzielnym hostingu Umami jest już udostępniany z Państwa własnej domeny, a dwie zmienne idą dalej: TRACKER_SCRIPT_NAME nadaje skryptowi inną nazwę niż script.js, a COLLECT_API_ENDPOINT zmienia nazwę punktu zbierania danych, zamiast /api/send. Skrypt sam wywołuje wtedy nowy punkt; na Państwa stronach zmienia się jedynie źródło kodu śledzącego.

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

Przydatne ustawienia

Te zmienne środowiskowe trafiają do usługi umami w compose.yaml, a następnie docker compose up -d tworzy kontener na nowo, aby je uwzględnił:

Kopie zapasowe

Wszystko, co przechowuje Umami, znajduje się w jego bazie PostgreSQL: konta, witryny, zespoły i statystyki. Proszę zrzucać ją codziennie i tuż przed każdą aktualizacją: przy samodzielnym hostingu dane te są przechowywane bez limitu czasu. Obok bazy plik .env zawiera sekrety, bez których nie da się z niej korzystać:

Zrzut bazy w trakcie jej działania

pg_dump wykonuje spójny zrzut, gdy baza jest w użyciu. Format niestandardowy, -Fc, jest skompresowany i przywraca się go przez pg_restore:

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

Proszę zaplanować to polecenie na serwerze co najmniej raz dziennie, porządkować zrzuty, które się gromadzą, i wysyłać kopię w inne miejsce. Przechowywane na dysku serwera, zrzuty te trafiają także do jego nocnych kopii zapasowych.

Przywracanie

1. Proszę zatrzymać Umami, zostawiając działającą bazę: docker compose stop umami.
2. Proszę przywrócić zrzut do bazy, zastępując istniejące obiekty.
3. Proszę ponownie uruchomić Umami, a następnie sprawdzić, czy witryny i ich statystyki są na miejscu.

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

Proszę powtarzać to ćwiczenie od czasu do czasu, na kopii: w ten sposób sprawdzają Państwo, że kopia zapasowa działa.

Aktualizacje

Dokumentacja podaje dwa polecenia, wydawane z katalogu z compose.yaml. Baza pozostaje w swoim woluminie:

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

Przy ponownym uruchomieniu kontener sam stosuje migracje schematu. Wersja 3.4.0 z 17 września 2026 roku zawierała dwie, dla adnotacji i kluczy API; wersja 3.4.1 z 23 października 2026 roku nie zawiera żadnej. Po dużej aktualizacji, takiej jak przejście na wersję 3, dokumentacja proponuje uruchomić ANALYZE w PostgreSQL, aby panele odzyskały szybkość:

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

• Informacje o wydaniach mówią, co zmienia każda wersja. Wersja 3.4.1 to pilna poprawka bezpieczeństwa, która aktualizuje Next.js i obraz bazowy Node.js; jej notatki proszą każdą samodzielnie hostowaną instancję o aktualizację przez ponowne pobranie obrazu.
• Z wersji 2 na MySQL: wersja 3 nie obsługuje już MySQL. Przewodnik migracji projektu przenosi dane do PostgreSQL na wersji 2.19.0, przed aktualizacją do wersji 3.
• Sam PostgreSQL: proszę zachować tag postgres:15-alpine z pliku. Przejście na nową wersję główną PostgreSQL wymaga zrzutu i przywrócenia albo pg_upgrade.

Kto za co odpowiada na Managed VPS

Samodzielny hosting wymaga prowadzenia serwera, oprócz samej aplikacji. Na Managed VPS nasze zespoły przejmują serwer i proaktywnie czuwają nad Państwa instancją; Umami pozostaje Państwa oprogramowaniem, z jego ustawieniami i danymi.

Jeśli wolą Państwo, aby nasze zespoły interweniowały w samej aplikacji, usługa ta jest rozliczana godzinowo lub ryczałtowo, z wyceną przekazaną przed interwencją.