Umami auf einem Managed VPS hosten: Ihre Webanalyse auf Ihrem Server

Was Umami kann

Umami ist eine quelloffene Plattform für Web- und Produktanalyse. Seine Dokumentation beschreibt ein Werkzeug, das Besucherverkehr, Kampagnen, Besucherverhalten, Conversions, Bindung und Umsatz zusammenführt, vom ersten Besuch bis zu den Ergebnissen, die für Ihr Unternehmen zählen. Es ist in TypeScript auf Basis von Next.js geschrieben, und sein Docker-Image läuft unter einem Konto ohne Sonderrechte.

• Die Akquise: Seitenaufrufe, Besucher, Verweisquellen, Länder, Geräte und Echtzeitaktivität, mit UTM-Kampagnen, Kurzlinks und Tracking-Pixeln.
• Das Verhalten: eigene Ereignisse, Pfade, Sitzungsaufzeichnungen, Heatmaps, Segmente, Kohorten und Bindung.
• Die Conversion: Ziele, Trichter, Attribution und Umsatzverfolgung nach Seite und nach Kampagne.
• Das Teilen: Dashboards, Teams, eine öffentliche Freigabe-URL, eine API und ein MCP-Server mit Lesezugriff für Ihren KI-Assistenten.
• Moderne Websites: Laut FAQ erfasst Umami die Navigation in Single-Page-Anwendungen selbstständig, ohne zusätzliche Einstellung.

Eine Instanz verfolgt mehrere Websites: Jede erhält ihre eigene ID und ihr eigenes Tracking-Skript, und Ihre Kolleginnen und Kollegen finden sich über Konten und Teams zurecht.

Was die MIT-Lizenz erlaubt

Umami wird unter der MIT-Lizenz veröffentlicht, im Namen von Umami Software, Inc. Sie gewährt kostenlos das Recht, die Software zu nutzen, zu kopieren, zu ändern, zusammenzuführen, zu veröffentlichen, zu verbreiten, unterzulizenzieren und Kopien davon zu verkaufen. Sie können sie also für Ihr Unternehmen und für die Websites Ihrer Kunden betreiben, ohne eine Lizenz zu kaufen.

Ihre einzige Bedingung: Der Urheberrechtshinweis und der Erlaubnishinweis begleiten alle Kopien oder wesentlichen Teile der Software. Wie jede MIT-Lizenz stellt sie die Software „wie besehen“ bereit, ohne Gewährleistung.

Cookies und personenbezogene Daten: was das Projekt sagt

Die Dokumentation stellt Umami als Analyse ohne Cookies vor, ohne websiteübergreifendes Tracking und ohne automatische Erhebung personenbezogener Daten. Selbst gehostet, bewahrt es Ihre Statistiken auf Ihrem eigenen Server: Sie entscheiden, wo sie liegen und wie lange sie bleiben.

Drei Einstellungen des Tracking-Skripts gehen auf Wunsch weiter: data-exclude-search entfernt die Suchparameter aus den erfassten URLs, data-exclude-hash entfernt den Hash, und data-do-not-track schaltet das Tracking für Browser ab, die die Präferenz Do Not Track übermitteln. Die Dokumentation weist darauf hin, dass diese letzte Einstellung für sich allein keine vollständige Lösung für das Einwilligungsmanagement ist.

Wenn Sie angemeldete Besucher mit data-distinct-id oder umami.identify() identifizieren, empfiehlt die Dokumentation eine interne Nutzer-ID oder einen Hash statt einer E-Mail-Adresse: Der Wert ist im HTML der Seite lesbar.

Die Installation mit Docker Compose und PostgreSQL

Das Repository liefert eine docker-compose.yml, die Umami und seine PostgreSQL-Datenbank startet. Seit Version 3 ist PostgreSQL die einzige unterstützte Datenbank, mindestens in Version 12.14, und die Dokumentation empfiehlt, sie auf die Zeitzone UTC einzustellen. Legen Sie auf einem Server, auf dem Docker installiert ist, einen Ordner an und beginnen Sie mit den Geheimnissen, per Zufall mit openssl erzeugt, wie es die Dokumentation vorschlägt:

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

Legen Sie dann diese compose.yaml daneben. Sie folgt der Datei des Projekts in Version 3.4.1, mit zwei Änderungen: Die Geheimnisse kommen aus der Datei .env, und der Port wird nur auf 127.0.0.1 veröffentlicht.

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: die einzige Pflichtvariable, die Verbindungszeichenkette der Datenbank. Das hexadezimale Passwort wird unverändert eingesetzt; ein Passwort mit Sonderzeichen müsste prozentkodiert werden.
• APP_SECRET: eine zufällige Zeichenkette, die die Authentifizierungstoken absichert, für jede Installation eigen. Im Code der Version 3.4.1 fließt sie auch in die Berechnung der Sitzungs-IDs ein: Halten Sie sie stabil.
• TWO_FACTOR_ENCRYPTION_KEY: 64 hexadezimale Zeichen, die die Geheimnisse der Zwei-Faktor-Authentifizierung verschlüsseln. Ohne ihn kann niemand die Zwei-Faktor-Authentifizierung aktivieren.
• Beim Start prüft der Container die Verbindung und die Version der Datenbank und wendet dann die Schemamigrationen selbst an. Beim ersten Start legt er die Tabellen und das Konto admin an. Die Prüfadresse /api/heartbeat antwortet {"ok":true}, sobald Umami bereit ist.
• Das Tag latest folgt der zuletzt veröffentlichten Version. Die Registry des Projekts veröffentlicht auch Versions-Tags wie 3.4.1, um die Version festzulegen, die Sie betreiben.

Die Installationsdokumentation nennt weder Arbeitsspeicher noch Prozessor. Die Größe hängt vom Besucherverkehr der verfolgten Websites und vom Umfang der aufbewahrten Daten ab. Auf einem Managed VPS beschreiben Sie uns Ihren Einsatz, und wir empfehlen Ihnen die passende Größe.

HTTPS: der Reverse Proxy

Umami lauscht über HTTP auf Port 3000, und die Dokumentation schlägt vor, es hinter Ihrem Webserver über einen Reverse Proxy auszuliefern. Geben Sie ihm eine eigene Subdomain, etwa stats.example.com, die mit A- und AAAA-Einträgen auf den Server zeigt. Umami unter einem Pfad auszuliefern, läuft über BASE_PATH, eine Variable, die beim Bau der Anwendung gelesen wird: Mit dem veröffentlichten Image ist die Subdomain der direkte Weg.

Der Proxy muss außerdem die Adresse des Besuchers weitergeben. Umami liest sie aus den Headern, die es erhält, darunter X-Real-IP und X-Forwarded-For: Es nutzt sie, um Besucher zu unterscheiden und ihr Land zu bestimmen. Wenn Ihr Proxy einen anderen Header verwendet, benennt ihn CLIENT_IP_HEADER.

Mit Caddy

Caddy bezieht das Zertifikat von Let’s Encrypt und aktiviert HTTPS selbstständig. Seine Direktive reverse_proxy setzt standardmäßig X-Forwarded-For: Diese drei Zeilen genügen.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

Mit Nginx und Certbot

Dieser Block folgt dem Nginx-Beispiel der Umami-Dokumentation und lauscht auf Port 80, damit Certbot HTTPS einrichten kann:

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 richtet anschließend das Zertifikat ein und kümmert sich um die Erneuerung:

sudo certbot --nginx

Die erste Anmeldung: das Admin-Konto und die Zwei-Faktor-Authentifizierung

Wenn Umami seine Datenbank anlegt, eröffnet es ein Administratorkonto: Benutzername admin, Passwort umami. Die Dokumentation bittet darum, dieses Passwort bei der ersten Anmeldung zu ändern.

1. Öffnen Sie Ihre HTTPS-Adresse und melden Sie sich mit admin und umami an.
2. Öffnen Sie Settings über die Profilschaltfläche in der Seitenleiste, dann Profile, und klicken Sie auf Change password.
3. Aktivieren Sie im Reiter Security die Zwei-Faktor-Authentifizierung: Scannen Sie den QR-Code mit Ihrer Authenticator-App, geben Sie den sechsstelligen Code ein und bewahren Sie dann die zehn Backup-Codes sicher auf, denn sie werden nur einmal angezeigt.

• Die Zwei-Faktor-Authentifizierung verlangen: Ein Administrator kann sie über die Administrationsseiten für die ganze Instanz, für einen Nutzer oder für ein Team vorschreiben.
• Die Versuche: Fünf falsche Codes sperren weitere Versuche für 15 Minuten.
• Die Konten Ihres Teams: Die Administrationsseiten verwalten die Nutzer, Websites und Teams der ganzen Instanz.

Bewahren Sie TWO_FACTOR_ENCRYPTION_KEY bei Ihren Backups auf: Die Dokumentation warnt, dass der Verlust oder die Änderung dieses Schlüssels die gespeicherten Geheimnisse unlesbar macht, und jeder Nutzer muss sich dann erneut für die Zwei-Faktor-Authentifizierung registrieren.

Eine Website und ihr Tracking-Skript hinzufügen

1. Klicken Sie unter Websites auf Add website.
2. Geben Sie der Website einen Namen und dann ihre Domain an: Umami nutzt sie, um Ihre eigenen Seiten aus der Liste der Verweisquellen herauszufiltern.
3. Öffnen Sie Edit bei dieser Website und kopieren Sie den Code aus dem Abschnitt Tracking code.
4. Setzen Sie ihn in den <head> Ihrer Seiten und besuchen Sie dann Ihre Website: Die Daten erscheinen sofort im Dashboard.

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

• Es erscheint nichts? Die Dokumentation schlägt den Reiter Netzwerk der Entwicklerwerkzeuge des Browsers vor: Die Anfragen an Ihre Instanz sollten ohne Fehler hinausgehen.
• Next.js: Fügen Sie den Code mit der Komponente next/script ein statt mit einem einfachen Tag <script>.
• data-domains beschränkt das Tracking auf Ihre Produktionsdomains, was Ihre Testumgebungen aus den Statistiken heraushält.
• Ihre eigenen Besuche schließen Sie Website für Website über die Browserkonsole aus, mit localStorage.setItem('umami.disabled', 1).

Ein eigener Name für das Skript

Manche Werbeblocker sperren alles, was nach Analyse aussieht. Selbst gehostet wird Umami bereits von Ihrer eigenen Domain ausgeliefert, und zwei Variablen gehen weiter: TRACKER_SCRIPT_NAME gibt dem Skript einen anderen Namen als script.js, und COLLECT_API_ENDPOINT benennt den Erfassungsendpunkt um, statt /api/send. Das Skript ruft den neuen Endpunkt dann selbst auf; auf Ihren Seiten ändert sich nur die Quelle des Tracking-Codes.

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

Nützliche Einstellungen

Diese Umgebungsvariablen kommen in den Dienst umami der compose.yaml, danach erstellt docker compose up -d den Container neu, damit er sie übernimmt:

Die Backups

Alles, was Umami aufbewahrt, liegt in seiner PostgreSQL-Datenbank: Konten, Websites, Teams und Statistiken. Exportieren Sie sie jeden Tag und unmittelbar vor jedem Update: Selbst gehostet werden diese Daten ohne zeitliche Grenze aufbewahrt. Neben der Datenbank enthält die Datei .env die Geheimnisse, die sie nutzbar machen:

Die Datenbank im laufenden Betrieb exportieren

pg_dump erstellt einen konsistenten Export, während die Datenbank in Gebrauch ist. Das benutzerdefinierte Format, -Fc, ist komprimiert und wird mit pg_restore wiederhergestellt:

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

Planen Sie diesen Befehl auf dem Server mindestens einmal täglich, räumen Sie die Exporte auf, die sich ansammeln, und schicken Sie eine Kopie an einen anderen Ort. Auf der Festplatte des Servers abgelegt, fließen diese Exporte auch in dessen nächtliche Backups ein.

Wiederherstellen

1. Stoppen Sie Umami und lassen Sie die Datenbank laufen: docker compose stop umami.
2. Spielen Sie den Export in die Datenbank zurück und ersetzen Sie dabei die vorhandenen Objekte.
3. Starten Sie Umami neu und prüfen Sie dann, ob Ihre Websites und ihre Statistiken da sind.

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

Wiederholen Sie diese Übung von Zeit zu Zeit, an einer Kopie: So prüfen Sie, dass ein Backup funktioniert.

Die Updates

Die Dokumentation nennt zwei Befehle, auszuführen im Ordner der compose.yaml. Die Datenbank bleibt in ihrem Volume:

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

Beim Neustart wendet der Container die Schemamigrationen selbst an. Version 3.4.0 vom 17. September 2026 brachte zwei davon mit, für Anmerkungen und API-Schlüssel; Version 3.4.1 vom 23. Oktober 2026 bringt keine. Nach einem großen Versionssprung, etwa dem Wechsel auf Version 3, schlägt die Dokumentation vor, in PostgreSQL ANALYZE auszuführen, damit die Dashboards wieder ihre Geschwindigkeit erreichen:

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

• Die Release Notes sagen, was jede Version ändert. Version 3.4.1 ist eine Sicherheitskorrektur, die Next.js und das Node.js-Basisimage aktualisiert; ihre Notizen bitten jede selbst gehostete Instanz, durch erneutes Herunterladen des Images zu aktualisieren.
• Von einer Version 2 mit MySQL: Version 3 unterstützt MySQL nicht mehr. Der Migrationsleitfaden des Projekts überträgt die Daten unter Version 2.19.0 nach PostgreSQL, vor dem Wechsel auf Version 3.
• PostgreSQL selbst: Behalten Sie das Tag postgres:15-alpine der Datei. Der Wechsel auf eine neue Hauptversion von PostgreSQL erfordert Export und Wiederherstellung oder pg_upgrade.

Wer was tut auf einem Managed VPS

Beim Selbsthosting müssen Sie neben der Anwendung auch den Server betreuen. Auf einem Managed VPS übernehmen unsere Teams den Server und betreuen Ihre Instanz proaktiv; Umami bleibt Ihre Software, mit ihren Einstellungen und Daten.

Wenn unsere Teams lieber in der Anwendung selbst eingreifen sollen, wird diese Leistung nach Stunden oder pauschal abgerechnet, mit einem Kostenvoranschlag vor dem Eingriff.