Eseguire HitKeep come singolo binario Linux

L’installazione binaria di HitKeep è il percorso self-hosted più essenziale: un unico eseguibile Linux, DuckDB e NSQ integrati, senza database, cache o servizio di code esterni. Sceglila per eseguire web analytics su VPS o VM con poche risorse, Raspberry Pi, server bare metal o reti con accesso limitato dove Docker non è adatto.

HitKeep pubblica binari di release non impacchettati esclusivamente per server Linux: linux/amd64 e linux/arm64. Scarica il file adatto, rendilo eseguibile e avvialo.

Per dimensioni citabili dei binari, consumo di memoria, limiti dello storage, formati di esportazione e funzionalità escluse, consulta Dati e limiti. I binari Linux attuali occupano circa 100 MB.

Docker Compose è più semplice per la prima installazione

Se preferisci rete e volumi persistenti già predisposti invece di gestire personalmente un’unità systemd, usa la configurazione Docker Compose. Se non vuoi gestire server, aggiornamenti, SMTP o backup, scegli HitKeep Cloud.

Compatibilità Linux

I binari Linux pubblicati sono compilati su Ubuntu 22.04 e richiedono glibc 2.35+. Sono testati su:

• Ubuntu 22.04 o versioni successive
• Debian 12 o versioni successive
• Amazon Linux 2023
• altre distribuzioni basate su glibc con glibc 2.35+

Se il server usa una glibc precedente (per esempio Ubuntu 20.04, Debian 11 o Amazon Linux 2), usa invece la configurazione Docker Compose.

Target di compilazione supportati

Artefatto	Target
hitkeep-linux-amd64	Server e VM Linux a 64 bit
hitkeep-linux-arm64	Server Linux ARM64, Raspberry Pi, AWS Graviton, Hetzner CAX
Immagine Docker	linux/amd64 e linux/arm64

I binari sono destinati a host Linux con una glibc moderna. Usa Docker Compose quando ti serve l’immagine container o quando la distribuzione host è precedente alla baseline del binario.

L’installazione binaria è quindi indicata per:

• server bare metal e VM;
• ambienti con accesso di rete limitato;
• Raspberry Pi e server ARM (AWS Graviton, Hetzner CAX);
• organizzazioni che richiedono la superficie di attacco più ridotta possibile.

Avvio rapido

Scarica il binario

Scarica da GitHub Releases l’ultima release per la tua architettura:

# 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

Per reti con accesso limitato, scarica il binario e SHA256SUMS dalla pagina della release GitHub su una macchina connessa a Internet, verifica il checksum, quindi trasferisci il binario verificato al server di destinazione.

Esegui con systemd

Sui server Linux di produzione, usa systemd per avviare HitKeep al boot e riavviarlo in caso di errore.

Non esporre i segreti nell’elenco dei processi

Non passare mai HITKEEP_JWT_SECRET o password SMTP come flag della riga di comando: sarebbero visibili a tutti gli utenti tramite ps aux. Usa variabili d’ambiente o un file d’ambiente drop-in.

Ogni flag ha una variabile d’ambiente HITKEEP_* equivalente uno a uno (--public-url ↔ HITKEEP_PUBLIC_URL), quindi puoi configurare tutto tramite l’ambiente. L’unità seguente usa entrambe le forme solo per evitare che i segreti compaiano nella riga di comando. Il riferimento di configurazione elenca entrambi i formati per ogni opzione.

1. Crea un utente di servizio dedicato e la directory dei dati:

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

[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

In alternativa, usa un file d’ambiente drop-in per i segreti, così non restano nel file dell’unità:

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. Abilita e avvia il servizio:

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

Verifica

Controlla la release installata, lo stato del servizio e la disponibilità del 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 conferma che il processo è attivo. /readyz conferma che il database condiviso e tutti i database dei tenant aperti sono pronti.

Pubblicare HitKeep in una sottodirectory

La maggior parte delle installazioni dovrebbe usare un hostname dedicato, per esempio https://analytics.example.com. Per pubblicare HitKeep sotto un altro sito, imposta HITKEEP_PUBLIC_URL sul percorso esterno completo:

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

oppure:

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

Il reverse proxy deve inoltrare a HitKeep lo stesso prefisso senza rimuoverlo:

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

Quando l’URL pubblico contiene /hitkeep/, la dashboard inserisce <base href="/hitkeep/" />, le chiamate API restano sotto /hitkeep/api/... e lo snippet di tracciamento può essere installato così:

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

Se Web Vitals è abilitato, hk.js carica https://www.example.net/hitkeep/hk-vitals.js e invia i campioni a /hitkeep/ingest/web-vitals. Visualizzazioni di pagina ed eventi automatici seguono la stessa regola per /hitkeep/ingest e /hitkeep/ingest/event.

In modalità prefisso, HitKeep non espone alla radice /api/..., /hk.js né le route fallback della dashboard. /healthz e /readyz locali restano disponibili per i controlli di processo, container e Kubernetes.

Risoluzione dei problemi

Errore all’avvio: failed to get final advertise address

Se HitKeep termina subito con:

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

il livello di clustering integrato non è riuscito a determinare l’indirizzo IP da pubblicizzare per il traffico gossip. Accade normalmente in ambienti locali o di sviluppo, quando l’indirizzo di bind predefinito è 0.0.0.0:7946 ma l’host non ha un indirizzo di rete privato individuabile.

Per un’esecuzione locale a nodo singolo, associa esplicitamente l’indirizzo del cluster al loopback:

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

Oppure usa una variabile d’ambiente:

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

Per distribuzioni multinodo, imposta --bind-addr o HITKEEP_BIND_ADDR su un indirizzo privato reale raggiungibile dagli altri nodi, non sul loopback.

Aggiornamento

Leggi le ultime note di rilascio ed esegui un backup completo. Scarica il nuovo binario per la stessa architettura con il comando dell’avvio rapido, quindi sostituisci l’eseguibile a servizio fermo:

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

Conserva il binario precedente e il backup pre-aggiornamento finché il controllo di disponibilità e una richiesta di tracciamento non hanno entrambi esito positivo. Consulta le note prima di eseguire un downgrade: le release con migrazioni dei dati potrebbero non consentire l’uso di un binario precedente sui dati aggiornati.

Backup

Per un servizio in esecuzione, preferisci il worker di backup con checkpoint integrato in HitKeep. Aggiungi queste voci alla sezione [Service] dell’unità o a un drop-in systemd, quindi riavvia il servizio:

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

Per una copia diretta del filesystem, ferma prima HitKeep così il database e il WAL non possono cambiare separatamente:

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

La copia deve includere HITKEEP_DB_PATH, l’intero albero HITKEEP_DATA_PATH con i database dei tenant in tenants/*/hitkeep.db e ogni archivio da conservare. Consulta Backup e ripristino per comandi di ripristino e opzioni S3.

Pagine correlate

• Proxy attendibili — obbligatori dietro un reverse proxy
• Riferimento di configurazione
• Dati e limiti
• Conservazione dei dati

Non vuoi gestire personalmente servizi systemd, aggiornamenti e backup? Confronta HitKeep Cloud per l’hosting gestito in UE (Francoforte) o negli Stati Uniti (Virginia), con aggiornamenti senza interruzioni e backup automatici.