Umami hosten op een Managed VPS: uw webstatistieken op uw eigen server

Wat Umami doet

Umami is een opensourceplatform voor web- en productanalyse. De documentatie beschrijft een hulpmiddel dat verkeer, campagnes, gedrag van bezoekers, conversies, retentie en omzet samenbrengt, van het eerste bezoek tot de resultaten die voor uw bedrijf tellen. Het is in TypeScript geschreven op Next.js, en de Docker-image draait onder een account zonder bijzondere rechten.

• De acquisitie: paginaweergaven, bezoekers, verwijzers, landen, apparaten en realtime activiteit, met UTM-campagnes, korte links en trackingpixels.
• Het gedrag: eigen events, trajecten, sessieherhalingen, heatmaps, segmenten, cohorten en retentie.
• De conversie: doelen, funnels, attributie en opvolging van de omzet per pagina en per campagne.
• Het delen: dashboards, teams, een openbare deel-URL, een API en een MCP-server met alleen leestoegang voor uw AI-assistent.
• Moderne sites: de FAQ vermeldt dat Umami de navigatie tussen pagina's in single-page applications zelf volgt, zonder extra instelling.

Eén instantie volgt meerdere websites: elke site krijgt een eigen ID en een eigen trackingscript, en uw collega's vinden hun weg via accounts en teams.

Wat de MIT-licentie toestaat

Umami wordt gepubliceerd onder de MIT-licentie, op naam van Umami Software, Inc. Die kent kosteloos het recht toe om kopieën van de software te gebruiken, te kopiëren, te wijzigen, samen te voegen, te publiceren, te verspreiden, in sublicentie te geven en te verkopen. U kunt het dus draaien voor uw bedrijf en voor de websites van uw klanten, zonder een licentie te kopen.

De enige voorwaarde: de copyrightvermelding en de toestemmingsvermelding gaan mee met alle kopieën of wezenlijke delen van de software. Zoals elke MIT-licentie levert ze de software “zoals hij is”, zonder garantie.

Cookies en persoonsgegevens: wat het project zegt

De documentatie stelt Umami voor als analyse zonder cookies, zonder tracking over sites heen en zonder automatische verzameling van persoonsgegevens. Zelf gehost blijven uw statistieken op uw eigen server: u beslist waar ze staan en hoe lang ze blijven.

Drie instellingen van het trackingscript gaan verder, als u dat wilt: data-exclude-search haalt de zoekparameters uit de geregistreerde URL's, data-exclude-hash haalt de hash weg, en data-do-not-track schakelt de tracking uit voor browsers die de voorkeur Do Not Track doorgeven. De documentatie merkt op dat deze laatste instelling op zichzelf geen volledige oplossing voor toestemmingsbeheer is.

Identificeert u aangemelde bezoekers met data-distinct-id of umami.identify(), dan raadt de documentatie een interne gebruikers-ID of een hash aan in plaats van een e-mailadres: de waarde is leesbaar in de HTML van de pagina.

De installatie met Docker Compose en PostgreSQL

De repository levert een docker-compose.yml mee die Umami en zijn PostgreSQL-database start. Sinds versie 3 is PostgreSQL de enige ondersteunde database, minimaal versie 12.14, en de documentatie raadt aan haar op de tijdzone UTC in te stellen. Maak op een server waar Docker is geïnstalleerd een map aan en begin met de geheimen, willekeurig gegenereerd met openssl, zoals de documentatie voorstelt:

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

Plaats daarna dit compose.yaml ernaast. Het volgt het bestand van het project op versie 3.4.1, met twee wijzigingen: de geheimen komen uit het bestand .env, en de poort wordt alleen op 127.0.0.1 gepubliceerd.

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: de enige verplichte variabele, de verbindingsreeks van de database. Het hexadecimale wachtwoord gaat er ongewijzigd in; een wachtwoord met speciale tekens zou procentcodering vragen.
• APP_SECRET: een willekeurige tekenreeks die de authenticatietokens beveiligt, uniek voor elke installatie. In de code van versie 3.4.1 telt ze ook mee in de berekening van de sessie-ID's: houd haar stabiel.
• TWO_FACTOR_ENCRYPTION_KEY: 64 hexadecimale tekens die de geheimen van de tweestapsverificatie versleutelen. Zonder deze sleutel kan niemand tweestapsverificatie inschakelen.
• Bij het opstarten controleert de container de verbinding met de database en haar versie, en past hij daarna zelf de schemamigraties toe. Bij de eerste start maakt hij de tabellen en het account admin aan. De sonde /api/heartbeat antwoordt {"ok":true} zodra Umami klaar is.
• De tag latest volgt de laatst gepubliceerde versie. Het register van het project publiceert ook versietags, zoals 3.4.1, om de versie vast te leggen die u draait.

De installatiedocumentatie noemt geen cijfer voor geheugen of CPU. De grootte hangt af van het verkeer van de gevolgde websites en van het volume aan gegevens dat u bewaart. Vertel ons op een managed VPS over uw gebruik, dan raden wij u de passende grootte aan.

HTTPS: de reverse proxy

Umami luistert via HTTP op poort 3000, en de documentatie stelt voor het achter uw webserver aan te bieden, via een reverse proxy. Geef het een eigen subdomein, zoals stats.example.com, dat met A- en AAAA-records naar de server wijst. Umami onder een pad aanbieden loopt via BASE_PATH, een variabele die wordt gelezen wanneer de applicatie wordt gebouwd: met de gepubliceerde image is het subdomein de rechtstreekse weg.

De proxy moet ook het adres van de bezoeker doorgeven. Umami leest het uit de headers die het ontvangt, waaronder X-Real-IP en X-Forwarded-For: het gebruikt het om bezoekers van elkaar te onderscheiden en hun land te bepalen. Gebruikt uw proxy een andere header, dan noemt CLIENT_IP_HEADER die.

Met Caddy

Caddy verkrijgt zelf het Let's Encrypt-certificaat en schakelt HTTPS zelf in. Zijn directive reverse_proxy zet standaard X-Forwarded-For: deze drie regels zijn alles wat u nodig hebt.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Met Nginx en Certbot

Dit blok volgt het Nginx-voorbeeld uit de documentatie van Umami, en luistert op poort 80 zodat Certbot HTTPS kan plaatsen:

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 plaatst daarna het certificaat en zorgt voor de vernieuwing ervan:

sudo certbot --nginx

De eerste aanmelding: het account admin en de tweestapsverificatie

Wanneer Umami zijn database aanmaakt, opent het een beheerdersaccount: gebruikersnaam admin, wachtwoord umami. De documentatie vraagt dit wachtwoord bij uw eerste aanmelding te wijzigen.

1. Open uw HTTPS-adres en meld u aan met admin en umami.
2. Open Settings via de profielknop in de zijbalk, daarna Profile, en klik op Change password.
3. Schakel in het tabblad Security de tweestapsverificatie in: scan de QR-code met uw authenticator-app, voer de code van zes cijfers in en bewaar daarna de tien herstelcodes op een veilige plek, want ze worden maar één keer getoond.

• Tweestapsverificatie verplichten: een beheerder kan haar verplichten voor de hele instantie, voor één gebruiker of voor één team, vanaf de beheerpagina's.
• De pogingen: na vijf foute codes worden verdere pogingen 15 minuten geblokkeerd.
• De accounts van uw team: de beheerpagina's beheren de gebruikers, websites en teams van de hele instantie.

Bewaar TWO_FACTOR_ENCRYPTION_KEY bij uw back-ups: de documentatie waarschuwt dat het verlies of de wijziging van deze sleutel de opgeslagen geheimen onleesbaar maakt, waarna elke gebruiker de tweestapsverificatie opnieuw moet instellen.

Een website en zijn trackingscript toevoegen

1. Klik in Websites op Add website.
2. Geef de website een naam, en daarna zijn domein: Umami gebruikt het om uw eigen pagina's uit de lijst met verwijzers te filteren.
3. Open Edit bij die website en kopieer de code uit de sectie Tracking code.
4. Plak die in de <head> van uw pagina's en bezoek daarna uw website: de gegevens verschijnen meteen in het dashboard.

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

• Verschijnt er niets? De documentatie stelt het tabblad netwerk van de ontwikkelaarstools van de browser voor: de verzoeken naar uw instantie moeten zonder fouten vertrekken.
• Next.js: voeg de code toe met de component next/script in plaats van een gewone tag <script>.
• data-domains beperkt de tracking tot uw productiedomeinen, zodat uw testomgevingen buiten de statistieken blijven.
• Uw eigen bezoeken sluit u per website uit, vanuit de console van de browser, met localStorage.setItem('umami.disabled', 1).

Een eigen naam voor het script

Sommige adblockers blokkeren alles wat op statistieken lijkt. Zelf gehost wordt Umami al vanaf uw eigen domein aangeboden, en twee variabelen gaan verder: TRACKER_SCRIPT_NAME geeft het script een andere naam dan script.js, en COLLECT_API_ENDPOINT hernoemt het verzamelpunt, in plaats van /api/send. Het script roept het nieuwe punt dan zelf aan; op uw pagina's verandert alleen de bron van de trackingcode.

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

Nuttige instellingen

Deze omgevingsvariabelen komen in de dienst umami van compose.yaml, waarna docker compose up -d de container opnieuw aanmaakt om ze toe te passen:

De back-ups

Alles wat Umami bewaart, staat in zijn PostgreSQL-database: accounts, websites, teams en statistieken. Exporteer haar elke dag en vlak voor elke update: zelf gehost worden deze gegevens zonder tijdslimiet bewaard. Naast de database bevat het bestand .env de geheimen die haar bruikbaar maken:

De database exporteren terwijl ze draait

pg_dump maakt een consistente export terwijl de database in gebruik is. Het eigen formaat, -Fc, is gecomprimeerd en wordt teruggezet met pg_restore:

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

Plan deze opdracht op de server minstens één keer per dag in, ruim de exports, die zich opstapelen, regelmatig op, en stuur een kopie naar elders. Staan deze exports op de schijf van de server, dan vallen ze ook onder de nachtelijke back-ups.

Terugzetten

1. Stop Umami en laat de database draaien: docker compose stop umami.
2. Zet de export terug in de database, waarbij bestaande objecten worden vervangen.
3. Start Umami opnieuw, en controleer daarna dat uw websites en hun statistieken er zijn.

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

Herhaal deze oefening af en toe, op een kopie: zo controleert u of een back-up werkt.

De updates

De documentatie geeft twee opdrachten, vanuit de map van compose.yaml. De database blijft in haar volume:

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

Bij het herstarten past de container zelf de schemamigraties toe. Versie 3.4.0, van 17 september 2026, bracht er twee mee, voor annotaties en API-sleutels; versie 3.4.1, van 23 oktober 2026, bevat er geen. Na een grote upgrade, zoals de overstap naar versie 3, stelt de documentatie voor ANALYZE uit te voeren in PostgreSQL, zodat de dashboards hun snelheid terugkrijgen:

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

• De release-opmerkingen vermelden wat elke versie verandert. Versie 3.4.1 is een beveiligingsfix die Next.js en de basisimage van Node.js bijwerkt; de opmerkingen ervan vragen elke zelf gehoste instantie bij te werken door de image opnieuw op te halen.
• Vanaf een versie 2 op MySQL: versie 3 ondersteunt MySQL niet meer. De migratiegids van het project verhuist de gegevens naar PostgreSQL op versie 2.19.0, vóór de upgrade naar versie 3.
• PostgreSQL zelf: behoud de tag postgres:15-alpine van het bestand. De overstap naar een nieuwe hoofdversie van PostgreSQL vraagt een export en terugzetten, of pg_upgrade.

Wie doet wat op een managed VPS

Self-hosting vraagt dat u naast de applicatie ook de server beheert. Op een managed VPS neemt ons team de server voor zijn rekening en houdt het uw instantie proactief in de gaten; Umami blijft uw software, met zijn instellingen en gegevens.

Wilt u liever dat ons team in de applicatie zelf ingrijpt, dan wordt die dienstverlening per uur of tegen een vast bedrag gefactureerd, met een offerte voordat het werk begint.