HitKeep als einzelne Linux-Binärdatei betreiben

Die Binärinstallation ist der schlankste Weg, HitKeep selbst zu hosten: eine ausführbare Linux-Datei, eingebettetes DuckDB, eingebettetes NSQ und kein externer Datenbank-, Cache- oder Queue-Dienst. Nutze sie für Webanalyse auf einem ressourcensparenden VPS, einer VM, einem Raspberry Pi, einem Bare-Metal-Server oder in einem eingeschränkten Netzwerk, in dem Docker nicht passt.

HitKeep veröffentlicht rohe Release-Binärdateien ausschließlich für Linux-Server: linux/amd64 und linux/arm64. Lade die passende Datei herunter, mache sie ausführbar und starte sie.

Zitierfähige Angaben zu Binärgröße, Speicherbedarf, Speichergrenzen, Exportformaten und Nicht-Zielen findest du unter Fakten und Grenzen. Aktuelle Linux-Release-Binärdateien sind etwa 100 MB groß.

Unterstützte Build-Ziele

Artefakt	Ziel
`hitkeep-linux-amd64`	64-Bit-Linux-Server und VMs
`hitkeep-linux-arm64`	ARM64-Linux-Server, Raspberry Pi, AWS Graviton, Hetzner CAX
Docker-Image	`linux/amd64` und `linux/arm64`

Rohe Binärdateien sind für Linux-Hosts mit moderner glibc vorgesehen. Verwende Docker Compose, wenn du das Container-Image benötigst oder die Host-Distribution älter als die Binär-Baseline ist.

Damit ist die Binärinstallation die richtige Wahl für:

Bare-Metal-Server und VMs
eingeschränkte Netzwerkumgebungen
Raspberry Pi und ARM-Server (AWS Graviton, Hetzner CAX)
Organisationen, die eine möglichst kleine Angriffsfläche benötigen

Schnellstart

Binärdatei herunterladen

Lade das neueste Release für deine Architektur aus den GitHub Releases herunter:

# Linux AMD64 (most common VPS/server)
curl -L https://github.com/pascalebeier/hitkeep/releases/latest/download/hitkeep-linux-amd64 \
  -o hitkeep && chmod +x hitkeep && sudo mv hitkeep /usr/local/bin/hitkeep

# Linux ARM64 (Raspberry Pi, AWS Graviton, Hetzner CAX)
curl -L https://github.com/pascalebeier/hitkeep/releases/latest/download/hitkeep-linux-arm64 \
  -o hitkeep && chmod +x hitkeep && sudo mv hitkeep /usr/local/bin/hitkeep

Für eingeschränkte Netzwerke: Lade die Binärdatei und SHA256SUMS auf einem Rechner mit Internetzugang von der GitHub-Release-Seite herunter, prüfe die Prüfsumme und übertrage anschließend die verifizierte Binärdatei auf den Zielserver.

Mit systemd betreiben

Verwende auf produktiven Linux-Servern systemd, damit HitKeep beim Booten startet und nach einem Fehler neu gestartet wird.

Jedes Flag besitzt eine gleichwertige HITKEEP_*-Umgebungsvariable (--public-url ↔ HITKEEP_PUBLIC_URL). Du kannst daher auf Wunsch alles über die Umgebung konfigurieren. Die Unit unten nutzt beides nur, um Geheimnisse aus der sichtbaren Kommandozeile herauszuhalten. Die Konfigurationsreferenz führt für jede Option beide Formen auf.

1. Eigenen Dienstbenutzer und Datenverzeichnis erstellen:

sudo useradd -r -s /bin/false hitkeep
sudo mkdir -p /var/lib/hitkeep/data /var/lib/hitkeep/archive
sudo chown -R hitkeep:hitkeep /var/lib/hitkeep

2. /etc/systemd/system/hitkeep.service erstellen:

[Unit]
Description=HitKeep Analytics
After=network.target

[Service]
Type=simple
User=hitkeep
Group=hitkeep
WorkingDirectory=/var/lib/hitkeep

# Sensitive values via environment (not visible in ps aux).
# Generate the secret with: openssl rand -hex 32
Environment="HITKEEP_JWT_SECRET=change-this-to-a-long-random-string"
Environment="HITKEEP_MAIL_PASSWORD=your-smtp-password"

# General configuration via flags
ExecStart=/usr/local/bin/hitkeep \
  --public-url=https://analytics.example.com \
  --db-path=/var/lib/hitkeep/data/hitkeep.db \
  --data-path=/var/lib/hitkeep/data \
  --archive-path=/var/lib/hitkeep/archive \
  --http-addr=:8080

Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Alternativ kannst du eine Drop-in-Umgebungsdatei für Geheimnisse verwenden. Das ist sicherer, weil die Werte nicht in der Unit-Datei stehen:

sudo mkdir -p /etc/systemd/system/hitkeep.service.d
sudo tee /etc/systemd/system/hitkeep.service.d/secrets.conf << 'EOF'
[Service]
Environment="HITKEEP_JWT_SECRET=your-secret-here"
EOF
sudo chmod 600 /etc/systemd/system/hitkeep.service.d/secrets.conf

3. Aktivieren und starten:

sudo systemctl daemon-reload
sudo systemctl enable --now hitkeep
sudo systemctl status hitkeep

Installation prüfen

Prüfe installiertes Release, Dienstzustand und Datenbankbereitschaft:

hitkeep --version
sudo systemctl --no-pager status hitkeep
curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/readyz

/healthz bestätigt, dass der Prozess läuft. /readyz bestätigt, dass die gemeinsame Datenbank und jede geöffnete Mandantendatenbank bereit sind.

HitKeep unter einem Unterverzeichnis einbinden

Die meisten Installationen sollten einen eigenen Analytics-Hostnamen wie https://analytics.example.com verwenden. Wenn du HitKeep unterhalb einer anderen Website veröffentlichen musst, setze HITKEEP_PUBLIC_URL auf den vollständigen externen Pfad:

Environment="HITKEEP_PUBLIC_URL=https://www.example.net/hitkeep/"

oder:

hitkeep --public-url=https://www.example.net/hitkeep/

Der Reverse Proxy muss dasselbe Pfadpräfix an HitKeep weiterleiten, ohne es zu entfernen:

www.example.net {
  handle /hitkeep* {
    reverse_proxy 127.0.0.1:8080
  }
}

Wenn die öffentliche URL /hitkeep/ enthält, fügt das Dashboard <base href="/hitkeep/" /> ein, API-Aufrufe bleiben unter /hitkeep/api/... und das Tracker-Snippet kann so installiert werden:

<script async src="https://www.example.net/hitkeep/hk.js"></script>

Wenn Web Vitals aktiviert sind, lädt hk.js die Datei https://www.example.net/hitkeep/hk-vitals.js und sendet Messwerte an /hitkeep/ingest/web-vitals. Seitenaufrufe und automatische Ereignisse folgen derselben Regel für /hitkeep/ingest und /hitkeep/ingest/event.

Im Pfadpräfix-Modus stellt HitKeep keine Root-Routen für /api/..., /hk.js oder den Dashboard-Fallback bereit. Lokale /healthz- und /readyz-Routen bleiben für Prozess-, Container- und Kubernetes-Prüfungen verfügbar.

Fehlerbehebung

Start schlägt mit `failed to get final advertise address` fehl

Wenn HitKeep sofort mit dieser Meldung beendet wird:

failed to get final advertise address: no private IP address found, and explicit IP not provided

konnte die eingebettete Cluster-Schicht nicht bestimmen, welche IP-Adresse für Gossip-Datenverkehr bekannt gegeben werden soll. Das passiert meist in lokalen oder Entwicklungsumgebungen, in denen 0.0.0.0:7946 als Standard-Bind-Adresse verwendet wird, der Host aber keine erkennbare private Netzwerkadresse besitzt.

Binde die Cluster-Adresse bei einem lokalen Einzelknoten ausdrücklich an Loopback:

./hitkeep --bind-addr=127.0.0.1:7946

Oder mit einer Umgebungsvariable:

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

Setze bei Mehrknoten-Bereitstellungen --bind-addr oder HITKEEP_BIND_ADDR auf eine echte private Adresse, die von den anderen Knoten erreichbar ist, statt auf Loopback.

Upgrade

Lies die aktuellen Release Notes und erstelle ein vollständiges Backup. Lade mit dem Schnellstart-Befehl die neue Binärdatei für dieselbe Architektur herunter und ersetze die ausführbare Datei, während der Dienst angehalten ist:

sudo systemctl stop hitkeep
sudo install -m 0755 ./hitkeep /usr/local/bin/hitkeep
sudo systemctl start hitkeep
curl --fail http://127.0.0.1:8080/readyz
hitkeep --version

Bewahre die vorherige Binärdatei und das Backup vor dem Upgrade auf, bis sowohl die Bereitschaftsprüfung als auch eine Tracking-Anfrage erfolgreich sind. Prüfe vor einem Downgrade die Release Notes; Releases mit Datenmigrationen unterstützen möglicherweise keine ältere Binärdatei auf bereits aktualisierten Daten.

Backup

Bevorzuge für einen laufenden Dienst den integrierten Worker für konsistente Checkpoint-Backups. Ergänze diese Einträge im Abschnitt [Service] der Unit oder in einem systemd-Drop-in und starte den Dienst anschließend neu:

Environment="HITKEEP_BACKUP_PATH=/var/lib/hitkeep/backups"
Environment="HITKEEP_BACKUP_INTERVAL=60"
Environment="HITKEEP_BACKUP_RETENTION=24"

Halte HitKeep vor einer rohen Dateisystemkopie an, damit sich Datenbank und WAL nicht unabhängig voneinander ändern können:

sudo systemctl stop hitkeep
rsync -a /var/lib/hitkeep/data/ /backup/hitkeep-$(date +%Y%m%d)/
rsync -a /var/lib/hitkeep/archive/ /backup/hitkeep-archive-$(date +%Y%m%d)/
sudo systemctl start hitkeep

Die Kopie muss den konfigurierten HITKEEP_DB_PATH, den vollständigen HITKEEP_DATA_PATH-Baum mit den Mandantendatenbanken unter tenants/*/hitkeep.db sowie alle benötigten Archivpfade enthalten. Unter Backups und Wiederherstellung findest du Wiederherstellungsbefehle und S3-Optionen.