Kör webbanalys med Umami och Podman utan root

Det här sätter du upp

Umami räknar besöken på dina webbplatser: vilka sidor som visas, var besökarna kom ifrån, deras land, webbläsare och enhet, utan kakor. Du lägger till en script-tagg på din webbplats och ser siffrorna i Umamis instrumentpanel. Uppgifterna om besökarna stannar på din server.

Här körs den som en pod under en egen användare som heter umami, bakom Caddy från Podman-guiden: Umami själv och PostgreSQL för dess data.

Umami utvecklas av Umami Software, Inc., ett företag registrerat i Delaware i USA, och är öppen källkod under MIT-licensen. Som standard får instrumentpanelen din webbläsare att hämta en bild från i.umami.is med Umamis versionsnummer och att fråga api.umami.is efter den senaste versionen. Båda svarar från Cloudflares nätverk. Instrumentpanelen hämtar också ikonerna för webbplatserna den visar från DuckDuckGos ikontjänst. Och varje gång Umami startar rapporterar databasverktyget den använder, Prisma, sin version, operativsystemet, Node.js-versionen och en hash av installationssökvägen till checkpoint.prisma.io, på servrar i USA. Steg 3 stänger av alla fyra. Besökarna på din webbplats kontaktar bara din egen server.

Varje steg nedan har körts på en ny Melonslab VC-P Alloy (2 vCPU, 8 GB) med Debian 13:

• Umamis inbyggda konto admin med lösenordet umami byttes via en SSH-tunnel innan Umami gick att nå från internet. Utifrån nekades sedan det gamla lösenordet. Tvåfaktorsautentisering fungerade.
• En sida på en annan webbplats, som samma Caddy serverade, besöktes i en webbläsare, och besöken syntes i Umami med besökarens riktiga land och stad.
• En besökare som skickade en påhittad adress i en X-Real-IP-header räknades under fel land tills raden CLIENT_IP_HEADER från steg 3 lades till, och under rätt land efter det.
• Med inställningarna i steg 3 skickade instrumentpanelen inga anrop till Umamis servrar eller till DuckDuckGo, och Umami gjorde inga DNS-uppslag alls när den startade.
• En dump av databasen återställdes, podman auto-update uppdaterade Umami 3.3.1 till 3.4.0, och allt startade igen av sig självt efter en omstart av servern.

Umami använde omkring 300 MB minne, nästan allt av det Umami själv. PostgreSQL använde omkring 20 MB. Umami lagrar allt i PostgreSQL. Plausible kör även ClickHouse, en databas byggd för stora mängder händelser, och använde omkring 600 MB i sin guide, med land men utan regioner och städer om du inte lägger till ett MaxMind-konto. Umami visar städer direkt.

Innan du börjar

Du behöver:

• en server uppsatt som i Podman-guiden, med Caddy igång, och skyddad med ufw;
• en A-post och en AAAA-post för stats.example.com som pekar på din server;
• en webbplats att mäta, här www.example.com.

Exemplen använder 203.0.113.10 som serverns adress. Byt genomgående ut namnen och adressen mot dina egna.

1. Skapa användaren

Som root:

useradd -m -s /bin/bash umami
loginctl enable-linger umami
machinectl shell umami@

Allt fram till steg 4 körs som umami.

2. Skapa hemligheterna

pw=$(openssl rand -hex 24)
printf %s "$pw" | podman secret create umami-db-password -
printf 'postgresql://umami:%s@127.0.0.1:5432/umami' "$pw" | podman secret create umami-database-url -
unset pw
openssl rand -hex 32 | tr -d '\n' | podman secret create umami-app-secret -
openssl rand -hex 32 | tr -d '\n' | podman secret create umami-2fa-key -

De två första innehåller databaslösenordet, en gång för PostgreSQL och en gång i adressen Umami ansluter till. Den tredje signerar Umamis inloggningar, och den fjärde skyddar tvåfaktorsautentiseringen.

3. Definiera podden

mkdir -p ~/.config/containers/systemd
cd ~/.config/containers/systemd

Skapa umami.pod:

[Pod]
PodName=umami
# Only Caddy, on this server, can reach Umami: the port is not open to the internet.
PublishPort=127.0.0.1:8112:3000

[Install]
WantedBy=default.target

Skapa umami-db.container:

[Container]
ContainerName=umami-db
Image=docker.io/library/postgres:17-alpine
Pod=umami.pod
Volume=umami-db:/var/lib/postgresql/data
Environment=POSTGRES_USER=umami POSTGRES_DB=umami
Secret=umami-db-password,type=env,target=POSTGRES_PASSWORD
AutoUpdate=registry

[Service]
Restart=always

Och umami-app.container:

[Unit]
After=umami-db.service

[Container]
ContainerName=umami-app
Image=ghcr.io/umami-software/umami:3
Pod=umami.pod
Secret=umami-database-url,type=env,target=DATABASE_URL
Secret=umami-app-secret,type=env,target=APP_SECRET
Secret=umami-2fa-key,type=env,target=TWO_FACTOR_ENCRYPTION_KEY
Environment=CLIENT_IP_HEADER=x-forwarded-for
Environment=TRACKER_SCRIPT_NAME=insights.js
Environment=DISABLE_TELEMETRY=1 DISABLE_UPDATES=1 CHECKPOINT_DISABLE=1
Environment=FAVICON_URL=https://{{domain}}/favicon.ico
AutoUpdate=registry

[Service]
Restart=always

Vad de sista raderna gör:

• CLIENT_IP_HEADER får Umami att ta besökarens adress från X-Forwarded-For, som Caddy alltid sätter själv. Utan den tittar Umami först på headers som X-Real-IP, som Caddy skickar vidare oförändrade från besökaren, så vem som helst skulle kunna välja vilket land den räknas under. Umami använder adressen för att slå upp land och stad, i en databas som finns inbyggd i avbilden, och för att skilja besökare åt. Den sparar inte adressen.
• TRACKER_SCRIPT_NAME gör spårningsskriptet tillgängligt under ett namn du väljer, utöver script.js, och spårningskoden i steg 6 använder sedan det namnet. Steg 6 förklarar vad det gör mot annonsblockerare, och vad det inte gör.
• TWO_FACTOR_ENCRYPTION_KEY, från den fjärde hemligheten, skyddar tvåfaktorhemligheterna i databasen. Utan den erbjuder Umami ingen tvåfaktorsautentisering.
• DISABLE_TELEMETRY och DISABLE_UPDATES stoppar instrumentpanelens bild från i.umami.is och dess versionskontroll mot api.umami.is. Utan versionskontrollen får du ingen notis om nya versioner, men steg 8 installerar dem ändå. CHECKPOINT_DISABLE stoppar Prismas rapport vid varje start.
• FAVICON_URL får instrumentpanelen att hämta varje webbplats ikon direkt från webbplatsen i stället för från DuckDuckGo.

Taggen 3 följer varje version av Umami 3, och Umami uppdaterar sin databas själv när den startar. PostgreSQL ligger kvar på version 17: en ny huvudversion av PostgreSQL kräver en dump och en återställning.

Starta den:

systemctl --user daemon-reload
systemctl --user start umami-pod
systemctl --user enable --now podman-auto-update.timer

Vid första starten laddas avbilderna ner. De upptar omkring 1,4 GB på disken, och det tar en minut eller två. curl -s http://127.0.0.1:8112/api/heartbeat skriver ut {"ok":true} när Umami är redo.

4. Byt standardlösenordet

Umami skapar ett konto admin med lösenordet umami, som vem som helst kan slå upp. Byt det innan Umami går att nå från internet. Öppna en SSH-tunnel till servern från din egen dator:

ssh -L 8112:127.0.0.1:8112 root@203.0.113.10

Öppna sedan http://localhost:8112 i webbläsaren. Det går direkt till Umami, inte via Caddy. Logga in med Username admin och Password umami. Välj ditt användarnamn, admin, längst ned till vänster, sedan Settings, Profile och Change password. Ange umami som Current password, ett långt eget lösenord som New password och Confirm password, och välj Save.

Slå sedan på tvåfaktorsautentisering: under Security i samma inställningar slår du på Enable 2FA, skannar QR-koden med en autentiseringsapp och anger den sexsiffriga kod som appen visar. Från och med då frågar Umami efter en kod efter lösenordet. Stäng tunneln med exit.

5. Sätt Caddy framför

Byt som root till Caddys användare med machinectl shell caddy@ och lägg till det här blocket sist i ~/Caddyfile:

stats.example.com {
    reverse_proxy 127.0.0.1:8112
}

Starta om Caddy med systemctl --user restart caddy. Kontrollera sedan, från valfri dator, att det gamla lösenordet inte längre fungerar:

curl -s -X POST https://stats.example.com/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "umami"}'

Svaret ska innehålla "code":"incorrect-username-password".

6. Mät din webbplats

Öppna https://stats.example.com, logga in och välj Add website under Websites. Ange ett Name och webbplatsens Domain, www.example.com, och välj Save. Välj sedan redigeringsikonen på webbplatsens rad. Under Tracking code finns taggen som ska in i <head> på varje sida på din webbplats:

<script defer src="https://stats.example.com/insights.js" data-website-id="2e75e9c8-6f8e-4fa6-b3fd-627a235d5a6f"></script>

Ditt Website ID är ett annat. När taggen finns på webbplatsen öppnar du en sida i webbläsaren: besöket syns under Realtime och Overview inom några sekunder, med ditt land och din stad under Location.

Annonsblockerare stoppar skriptet utifrån dess adress. EasyPrivacy, en lista som de flesta blockerare använder, blockerar script.js på alla värdar vars namn börjar med umami., och AdGuards spårningslista blockerar alla anrop till en sådan värd. Därför använder den här guiden stats.example.com. Med det namnet blockerade ingen av fyra vanliga listor (EasyList, EasyPrivacy, AdGuard Tracking Protection och uBlock Origins integritetslista) skriptet eller besöken det skickar, med något av skriptnamnen. TRACKER_SCRIPT_NAME hjälper alltså bara mot en lista som lägger till en regel för standardnamnet, och en blockerare som lägger till en regel för just din värd stoppar båda.

7. Säkerhetskopiera

Som umami:

mkdir -p ~/backup
podman exec umami-db pg_dump -U umami umami > ~/backup/umami.sql
podman secret inspect --showsecret --format '{{.SecretData}}' umami-2fa-key | tr -d '\n' > ~/backup/umami-2fa-key

Det sparar ditt konto, dina webbplatser och all deras statistik, och nyckeln som behövs för att läsa tvåfaktorhemligheterna i dumpen. Kopiera ~/backup till en annan maskin och förvara den säkert, eller låt restic ta dumpen varje natt (steg 6 där).

För att återställa, som umami:

systemctl --user stop umami-app
podman exec umami-db dropdb -U umami --force umami
podman exec umami-db createdb -U umami umami
podman exec -i umami-db psql -q -U umami umami < ~/backup/umami.sql
systemctl --user start umami-app

8. Uppdateringar

En gång om dygnet hämtar podman-auto-update.timer nyare avbilder för Umami och PostgreSQL och startar om podden med dem. För att uppdatera direkt, som umami:

podman auto-update
podman image prune -f

Den första raden listar båda avbilderna med true under UPDATED när det fanns något nytt. Den andra tar bort de gamla avbilderna, som upptar omkring 1 GB var.

Felsökning

Dina besök syns inte, och /api/send svarar {"beep":"boop"}. Umami ignorerar besök från botar och räknar webbläsare utan grafiskt gränssnitt (headless) och curl som botar. Testa med en vanlig webbläsare.

Besök från själva servern saknar land. Umami ignorerar adresser som tillhör maskinen den körs på, och inne i podden är serverns egna adresser poddens. Besök från andra maskiner påverkas inte.

Skriptet blockeras i din egen webbläsare. Din annonsblockerare har en regel för Umamis värd eller skriptnamn: se steg 6.