HitKeep uitvoeren als één Linux-binary

De binary-installatie van HitKeep is de kleinste zelfgehoste route: één uitvoerbaar Linux-bestand, ingebouwde DuckDB, ingebouwde NSQ en geen externe database-, cache- of wachtrijservice. Gebruik deze methode voor webanalyse op een lichte VPS, VM, Raspberry Pi, bare-metalserver of in een afgeschermd netwerk waar Docker niet geschikt is.

HitKeep publiceert losse releasebinary’s uitsluitend voor Linux-servers: linux/amd64 en linux/arm64. Download het juiste bestand, maak het uitvoerbaar en start het.

Raadpleeg Feiten en limieten voor citeerbare informatie over binarygrootte, geheugengebruik, opslaggrenzen, exportformaten en niet-doelstellingen. De huidige Linux-releasebinary’s zijn ongeveer 100 MB.

Docker Compose is eenvoudiger voor een eerste installatie

Wil je verpakte netwerkconfiguratie en permanente volumes in plaats van zelf een systemd-unit te beheren? Gebruik dan de Docker Compose-installatie. Wil je helemaal geen servers, upgrades, SMTP of back-ups beheren, gebruik dan HitKeep Cloud.

Linux-compatibiliteit

De gepubliceerde Linux-binary’s zijn gebouwd op Ubuntu 22.04 en vereisen glibc 2.35+. Ze zijn getest op:

• Ubuntu 22.04 of nieuwer
• Debian 12 of nieuwer
• Amazon Linux 2023
• andere op glibc gebaseerde distributies met glibc 2.35+

Draait je server op een oudere glibc (zoals Ubuntu 20.04, Debian 11 of Amazon Linux 2), gebruik dan de Docker Compose-installatie.

Ondersteunde buildtargets

Artefact	Target
hitkeep-linux-amd64	64-bits Linux-servers en VM’s
hitkeep-linux-arm64	ARM64 Linux-servers, Raspberry Pi, AWS Graviton, Hetzner CAX
Docker-image	linux/amd64 en linux/arm64

De losse binary’s zijn bedoeld voor Linux-hosts met een moderne glibc. Gebruik Docker Compose als je de containerimage nodig hebt of als de distributie op de host ouder is dan de binarybaseline.

Daarmee is de binary-installatie geschikt voor:

• bare-metalservers en VM’s;
• omgevingen met beperkte netwerktoegang;
• Raspberry Pi en ARM-servers (AWS Graviton, Hetzner CAX);
• organisaties die een zo klein mogelijk aanvalsoppervlak vereisen.

Snel aan de slag

De binary downloaden

Download de nieuwste release voor jouw architectuur via GitHub Releases:

# 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

Voor afgeschermde netwerken: download de binary en SHA256SUMS vanaf de GitHub-releasepagina op een machine met internettoegang, controleer de checksum en zet daarna de geverifieerde binary over naar de doelserver.

Uitvoeren met systemd

Gebruik op Linux-productieservers systemd, zodat HitKeep bij het opstarten wordt gestart en na een fout opnieuw wordt gestart.

Houd geheimen uit proceslijsten

Geef HITKEEP_JWT_SECRET of SMTP-wachtwoorden nooit als commandoregelopties door: via ps aux zijn ze voor alle gebruikers zichtbaar. Gebruik in plaats daarvan omgevingsvariabelen of een drop-in-omgevingsbestand.

Elke flag heeft een 1-op-1 equivalent als HITKEEP_*-omgevingsvariabele (--public-url ↔ HITKEEP_PUBLIC_URL). Je kunt dus desgewenst alles via de omgeving configureren. De unit hieronder gebruikt beide vormen alleen om geheimen buiten de zichtbare commandoregel te houden. De configuratiereferentie vermeldt beide vormen voor elke optie.

1. Maak een speciale servicegebruiker en datamap aan:

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. Maak /etc/systemd/system/hitkeep.service aan:

[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

Of gebruik een drop-in-omgevingsbestand voor geheimen (veiliger, omdat geheimen niet in het unitbestand staan):

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. Activeer en start:

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

Controleren

Controleer de geïnstalleerde release, servicestatus en gereedheid van de database:

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 bevestigt dat het proces actief is. /readyz bevestigt dat de gedeelde database en elke geopende tenantdatabase gereed zijn.

HitKeep onder een submap koppelen

Voor de meeste installaties is een apart analysehostnaam zoals https://analytics.example.com het beste. Moet HitKeep onder een andere site worden gepubliceerd, stel HITKEEP_PUBLIC_URL dan in op het volledige externe pad:

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

of:

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

De reverse proxy moet hetzelfde padprefix naar HitKeep doorsturen zonder het te herschrijven:

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

Als de openbare URL /hitkeep/ bevat, injecteert het dashboard <base href="/hitkeep/" />, blijven API-aanroepen onder /hitkeep/api/... en kan de trackingsnippet zo worden geïnstalleerd:

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

Als Web Vitals zijn ingeschakeld, laadt hk.js https://www.example.net/hitkeep/hk-vitals.js en verstuurt samples naar /hitkeep/ingest/web-vitals. Paginaweergaven en automatische gebeurtenissen volgen dezelfde regel voor /hitkeep/ingest en /hitkeep/ingest/event.

In padprefixmodus biedt HitKeep geen rootroutes voor /api/..., /hk.js of de dashboardfallback. Lokale /healthz en /readyz blijven beschikbaar voor proces-, container- en Kubernetescontroles.

Problemen oplossen

Opstarten mislukt met failed to get final advertise address

Als HitKeep onmiddellijk stopt met:

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

kon de ingebouwde clusterlaag niet bepalen welk IP-adres voor gossipverkeer moest worden aangekondigd. Dit gebeurt meestal in lokale of ontwikkelomgevingen waar 0.0.0.0:7946 als standaard bindadres wordt gebruikt, maar de host geen detecteerbaar privé-netwerkadres heeft.

Bind voor een lokale installatie met één node het clusteradres expliciet aan loopback:

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

Of met een omgevingsvariabele:

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

Stel bij implementaties met meerdere nodes --bind-addr of HITKEEP_BIND_ADDR in op een echt privéadres dat vanaf de andere nodes bereikbaar is, niet op loopback.

Upgraden

Lees de nieuwste releaseopmerkingen en maak een volledige back-up. Download met het snelstartcommando de nieuwe binary voor dezelfde architectuur en vervang het uitvoerbare bestand terwijl de service is gestopt:

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

Bewaar de vorige binary en de back-up van vóór de upgrade totdat zowel de gereedheidscontrole als een trackingverzoek slagen. Lees vóór een downgrade de releaseopmerkingen; na releases met datamigraties kan een oudere binary mogelijk niet met de geüpgradede data werken.

Back-up

Gebruik voor een actieve service bij voorkeur HitKeeps ingebouwde checkpointgebaseerde back-upworker. Voeg de volgende regels toe aan het onderdeel [Service] van de unit of aan een systemd-drop-in en herstart daarna de service:

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

Stop HitKeep vóór een onbewerkte kopie van het bestandssysteem, zodat de database en WAL niet onafhankelijk van elkaar kunnen wijzigen:

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

De kopie moet het geconfigureerde HITKEEP_DB_PATH, de volledige HITKEEP_DATA_PATH-structuur met tenantdatabases onder tenants/*/hitkeep.db en elk archiefpad dat je wilt bewaren bevatten. Zie Back-ups en herstel voor herstelcommando’s en S3-opties.

Gerelateerd

• Vertrouwde proxy’s — vereist bij gebruik achter een reverse proxy
• Configuratiereferentie
• Feiten en limieten
• Databewaring

Wil je systemd-services, upgrades en back-ups niet zelf beheren? Vergelijk HitKeep Cloud voor beheerde hosting in de EU (Frankfurt) of VS (Virginia), met zero-downtime-upgrades en automatische back-ups.