---
title: "HitKeep als einzelne Linux-Binärdatei betreiben | HitKeep"
description: "Betreibe HitKeep als selbst gehostete Webanalyse in einer einzigen Binärdatei auf Linux-Bare-Metal, VMs, Raspberry Pi oder in eingeschränkten Netzwerken."
canonical: "https://hitkeep.com/de/guides/installation/binary/"
---

# 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](https://hitkeep.com/reference/facts-and-limits/). Aktuelle Linux-Release-Binärdateien sind etwa 100 MB groß.

Docker Compose ist für die erste Installation einfacher

Wenn du paketierte Netzwerke und persistente Volumes bevorzugst, statt selbst eine systemd-Unit zu verwalten, nutze die [Docker-Compose-Einrichtung](https://hitkeep.com/de/guides/installation/docker-compose/). Wenn du Server, Upgrades, SMTP und Backups überhaupt nicht selbst betreiben möchtest, nutze [HitKeep Cloud](https://hitkeep.com/de/pricing/).

Linux-Kompatibilität

Die veröffentlichten Linux-Binärdateien werden auf Ubuntu 22.04 gebaut und benötigen `glibc 2.35+`. Sie werden getestet auf:

- Ubuntu 22.04 oder neuer
- Debian 12 oder neuer
- Amazon Linux 2023
- anderen glibc-basierten Distributionen mit `glibc 2.35+`

Wenn dein Server eine ältere glibc-Version nutzt, etwa Ubuntu 20.04, Debian 11 oder Amazon Linux 2, verwende stattdessen die [Docker-Compose-Einrichtung](https://hitkeep.com/de/guides/installation/docker-compose/).

## 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](https://github.com/pascalebeier/hitkeep/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.

Geheimnisse aus Prozesslisten heraushalten

Übergib `HITKEEP_JWT_SECRET` oder SMTP-Passwörter niemals als Kommandozeilen-Flags – sie sind über `ps aux` für alle Benutzer sichtbar. Nutze stattdessen Umgebungsvariablen oder eine Drop-in-Umgebungsdatei.

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](https://hitkeep.com/reference/configuration/) 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](https://github.com/PascaleBeier/hitkeep/releases/latest) 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](https://hitkeep.com/guides/data/backups-and-restore/) findest du Wiederherstellungsbefehle und S3-Optionen.

## Verwandte Themen

- [Vertrauenswürdige Proxys](https://hitkeep.com/guides/installation/trusted-proxies/) – erforderlich beim Betrieb hinter einem Reverse Proxy
- [Konfigurationsreferenz](https://hitkeep.com/reference/configuration/)
- [Fakten und Grenzen](https://hitkeep.com/reference/facts-and-limits/)
- [Datenaufbewahrung](https://hitkeep.com/guides/data/retention/)

Du möchtest systemd-Dienste, Upgrades und Backups nicht selbst verwalten? [HitKeep Cloud vergleichen](https://hitkeep.com/de/pricing/).

[Vorherige Seite Homebrew](https://hitkeep.com/de/guides/installation/homebrew/)[Nächste Seite Docker Compose](https://hitkeep.com/de/guides/installation/docker-compose/)