Was bauen wir?

Am Ende läuft HitKeep 2.12.0 als einzelner Container hinter deinem Traefik, erreichbar unter https://DEINE_DOMAIN. Du bekommst ein Dashboard mit Seitenaufrufen, Besuchern, Verweildauer, Referrern und Geräten – gespeist von einem winzigen JavaScript-Snippet, das du in deine Website einbaust. HitKeep arbeitet cookielos (kein Consent-Banner nötig) und speichert alles lokal in einer eingebetteten DuckDB-Datenbank. Das Image ist ein schlankes Distroless-Image (rund 71 MB), das komplett ohne externe Datenbank auskommt – ideal für einen kleinen VPS.

Voraussetzungen

• Ein Server mit Debian 13 und laufendem Docker (getestet auf einem netcup VPS).
• Ein Reverse Proxy mit Traefik, der TLS-Zertifikate per Let’s Encrypt holt. HitKeep bringt keinen eigenen HTTPS-Server mit – Traefik übernimmt die Verschlüsselung. Dieses Tutorial setzt das dort beschriebene proxy-Netz und den Resolver le voraus.
• Eine (Sub-)Domain, die auf deinen Server zeigt (A-/AAAA-Record). Wir nutzen im Beispiel DEINE_DOMAIN.
• Die Website, die du messen willst – HitKeep misst jede Seite, in die du das Snippet einbaust.

Schritt für Schritt

Schritt 1: JWT-Secret erzeugen

HitKeep signiert die Login-Sitzungen mit einem geheimen Schlüssel. Erzeuge dir einen zufälligen 32-Byte-Wert – nicht ausdenken, sondern generieren:

openssl rand -hex 32

Du bekommst eine 64 Zeichen lange Hex-Zeichenkette. Kopiere sie – sie kommt gleich in die Konfiguration. Ändert sich dieses Secret später, werden alle offenen Logins ungültig; halte es also stabil und geheim.

Schritt 2: Compose-Datei anlegen

Lege einen Ordner für den Stack an und wechsle hinein:

mkdir -p /opt/hitkeep && cd /opt/hitkeep

Erstelle die Datei compose.yaml. Ersetze DEINE_DOMAIN durch deine echte Domain und DEIN_JWT_SECRET durch den Wert aus Schritt 1:

services:
  hitkeep:
    image: pascalebeier/hitkeep:2.12.0
    container_name: hitkeep
    restart: unless-stopped
    environment:
      HITKEEP_PUBLIC_URL: https://DEINE_DOMAIN
      HITKEEP_JWT_SECRET: DEIN_JWT_SECRET
      HITKEEP_TRUSTED_PROXIES: 172.16.0.0/12
      HITKEEP_DB_PATH: /var/lib/hitkeep/data/hitkeep.db
      HITKEEP_DATA_PATH: /var/lib/hitkeep/data
      HITKEEP_ARCHIVE_PATH: /var/lib/hitkeep/archive
      HITKEEP_BACKUP_PATH: /var/lib/hitkeep/backups
    volumes:
      - hitkeep_data:/var/lib/hitkeep/data
      - hitkeep_archive:/var/lib/hitkeep/archive
      - hitkeep_backups:/var/lib/hitkeep/backups
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.hitkeep.rule=Host(`DEINE_DOMAIN`)"
      - "traefik.http.routers.hitkeep.entrypoints=websecure"
      - "traefik.http.routers.hitkeep.tls.certresolver=le"
      - "traefik.http.services.hitkeep.loadbalancer.server.port=8080"
    networks: [proxy]
volumes:
  hitkeep_data: {}
  hitkeep_archive: {}
  hitkeep_backups: {}
networks:
  proxy:
    external: true

Die wichtigsten Stellen im Detail:

• HITKEEP_PUBLIC_URL ist die öffentliche Adresse, unter der HitKeep erreichbar ist. Daraus baut die Oberfläche später den Tracking-Snippet und die Links. Sie muss exakt der URL entsprechen, unter der du HitKeep aufrufst – sonst kommst du in eine Login-Schleife.
• HITKEEP_TRUSTED_PROXIES ist der Knackpunkt hinter einem Reverse Proxy: Ohne diesen Wert sieht HitKeep als Absender jedes Aufrufs nur die interne IP von Traefik – dann landen alle Besucher als ein einziger. 172.16.0.0/12 deckt die Docker-Netze ab, sodass HitKeep dem X-Forwarded-For-Header von Traefik vertraut und die echte Besucher-IP auswertet.
• loadbalancer.server.port=8080 sagt Traefik, dass HitKeep intern auf Port 8080 lauscht. Der Container veröffentlicht selbst keine Ports nach außen – der Zugriff läuft ausschließlich über Traefik.
• Die vier _PATH-Variablen legen Datenbank, Daten, Archiv und Backups unter /var/lib/hitkeep/ ab; die passenden Volumes sorgen dafür, dass sie ein Update oder einen Neustart überleben.

Schritt 3: Stack starten und auf TLS warten

Starte den Container:

docker compose up -d

Prüfe nach ein paar Sekunden den Status:

docker compose ps

Du solltest den Container als healthy sehen – HitKeep bringt einen eigenen Healthcheck mit:

NAME      IMAGE                         SERVICE   STATUS                   PORTS
hitkeep   pascalebeier/hitkeep:2.12.0   hitkeep   Up 18 minutes (healthy)  7946/tcp, 8080/tcp

Traefik holt jetzt im Hintergrund das Let’s-Encrypt-Zertifikat für deine Domain. Prüfe von deinem eigenen Rechner aus, dass die Auslieferung des Tracking-Skripts steht:

curl -sI https://DEINE_DOMAIN/hk.js

Erwartete Ausgabe (gekürzt) – Status 200 und ein text/javascript-Typ, aggressiv gecacht:

HTTP/2 200
content-type: text/javascript; charset=utf-8
cache-control: public, max-age=31536000, immutable

Schritt 4: Admin-Konto anlegen

Rufe https://DEINE_DOMAIN im Browser auf. Beim allerersten Start begrüßt dich HitKeep mit der Ersteinrichtung. Lege hier dein Administrator-Konto an – Name, E-Mail-Adresse und ein Passwort. Nimm eine lange Passphrase oder ein per Passwortmanager erzeugtes Zufallspasswort; dieses Konto sieht sämtliche Statistiken und darf nicht an einem schwachen Passwort hängen:

Schritt 5: Website anlegen und Tracking-Code holen

Nach dem Login klickst du links oben bei Sites auf das Plus und legst deine Website an – als Domain trägst du die Domain der Seite ein, die du messen willst (z. B. DEINE_WEBSITE).

Öffne dann die Site-Einstellungen und wechsle auf den Reiter Tracking. Dort findest du den Live tracking verifier (der auf den ersten Treffer wartet) und die Konfiguration des Tracking-Codes samt Tracker-Host:

Der einzubauende Code besteht aus einer einzigen Zeile. HitKeep braucht keine Site-ID im Snippet – die Zuordnung passiert automatisch über die Domain der Seite, auf der das Skript läuft:

<script async src="https://DEINE_DOMAIN/hk.js"></script>

Automatisches Event-Tracking (ausgehende Klicks, Downloads, Formular-Absendungen) ist standardmäßig aktiv. Optional kannst du auf demselben Reiter „Web Vitals" einschalten, um Ladezeiten (LCP, INP, CLS, FCP, TTFB) mitzumessen, oder „Collect DNT" aktivieren, wenn du auch Besucher mit „Do Not Track" zählen willst – aus Datenschutzsicht ist die Voreinstellung (DNT respektieren) die sauberere.

Schritt 6: Tracking-Code in die Website einbauen

Füge die Snippet-Zeile aus Schritt 5 in den <head> deiner Website ein – bei einer statischen Seite direkt ins HTML-Template, bei einem CMS in den Kopfbereich bzw. ein „Custom HTML"-Feld. Durch das async-Attribut blockiert das Skript den Seitenaufbau nicht.

Rufe danach eine Seite deiner Website im Browser auf. Der Live tracking verifier aus Schritt 5 sollte innerhalb weniger Sekunden von „Waiting" auf einen ersten Treffer springen – das ist die Bestätigung, dass die Kette Website → hk.js → HitKeep steht.

Schritt 7: Das Dashboard prüfen

Sobald Treffer eintrudeln, füllt sich das Dashboard. Unter Dashboard siehst du die Kennzahlen deiner Website – Live-Besucher, Seitenaufrufe, eindeutige Sitzungen, Absprungrate, Verweildauer und den Traffic-Verlauf:

Weiter unten listet Latest Hits die einzelnen Aufrufe mit Pfad, Zeitpunkt, Referrer und Gerät auf – hier siehst du auf einen Blick, über welche Suchmaschinen und Verweise deine Besucher kommen:

Damit steht deine selbst gehostete Statistik: Jeder Aufruf deiner Website landet direkt in deiner eigenen Datenbank, ohne Umweg über Dritte.

Schritt 8: Mehr als nur Seitenaufrufe

Für den Anfang reichen Seitenaufrufe und Referrer – HitKeep kann aber deutlich mehr, und die Bausteine dafür findest du in der linken Navigation. Ein paar, die sich für die meisten Seiten lohnen:

• Goals (Ziele): Definiere ein Ereignis als Ziel – etwa das Absenden eines Kontaktformulars oder einen Klick auf „Kaufen". So misst du nicht nur, wie viele kommen, sondern wie viele das tun, was du willst.
• Funnels (Trichter): Verkette mehrere Schritte (Startseite → Produktseite → Warenkorb) und sieh, an welcher Stelle Besucher abspringen.
• Events: Neben den automatisch erfassten Ereignissen (ausgehende Klicks, Downloads, Formulare) kannst du eigene Ereignisse aus deinem Frontend senden.
• Web Vitals: Schaltest du sie im Tracking-Reiter ein, siehst du echte Ladezeiten deiner Besucher (LCP, INP, CLS) statt synthetischer Laborwerte.
• UTM: Kampagnen-Parameter (utm_source, utm_medium, utm_campaign) werden ausgewertet – praktisch, um Newsletter- oder Social-Reichweite auseinanderzuhalten.
• Email Reports: Lass dir eine Zusammenfassung regelmäßig per E-Mail schicken, statt selbst ins Dashboard schauen zu müssen.

Eine einzelne HitKeep-Instanz verwaltet außerdem beliebig viele Websites: Über das Plus bei Sites legst du weitere an, jede mit eigenem Snippet und eigenem Dashboard. Du brauchst also keinen zweiten Container, wenn du mehrere Projekte messen willst.

Wenn es nicht funktioniert

Wartung & Backups

Updates: HitKeep bewegt sich in der 2.x-Reihe zügig weiter – schau etwa monatlich in die Releases. Für ein Update setzt du den neuen Tag in der compose.yaml (ersetze 2.12.0 durch die neue Version) und ziehst ihn:

docker compose pull && docker compose up -d

Weil die Daten in Volumes liegen, bleiben deine Statistiken dabei erhalten. Pinne die Version bewusst auf einen festen Tag statt latest, damit ein Neustart dir nicht ungeplant eine neue Hauptversion unterschiebt.

Backups: Deine gesamte Statistik steckt in einer eingebetteten DuckDB-Datei (hitkeep.db samt Write-Ahead-Log hitkeep.db.wal) unter /var/lib/hitkeep/data. Sichere deshalb nicht eine Einzeldatei, sondern das komplette Volume hitkeep_data regelmäßig – am saubersten mit restic. Weil diese Dateien im laufenden Betrieb beschrieben werden, sicherst du sie am konsistentesten, indem du den Container kurz stoppst (docker compose stop), das Volume sicherst und wieder startest – oder das von HitKeep unter HITKEEP_BACKUP_PATH abgelegte Backup mit einbeziehst. Ein Backup, das du nie zurückgespielt hast, ist nur ein Hoffnungsschimmer: Teste die Wiederherstellung einmal auf einem Testsystem.

Aufräumen: Die Datenbank wächst mit dem Traffic. Behalte die Größe der Volumes im Blick (docker system df -v) und plane bei viel Traffic genügend Speicher ein.