---
title: "Eseguire HitKeep come singolo binario Linux | HitKeep"
description: "Esegui HitKeep come soluzione di web analytics self-hosted in un unico binario su Linux bare metal, VM, Raspberry Pi o reti con accesso limitato."
canonical: "https://hitkeep.com/it/guides/installation/binary/"
---

# 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](https://hitkeep.com/reference/facts-and-limits/). 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](https://hitkeep.com/it/guides/installation/docker-compose/). Se non vuoi gestire server, aggiornamenti, SMTP o backup, scegli [HitKeep Cloud](https://hitkeep.com/it/pricing/).

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](https://hitkeep.com/it/guides/installation/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](https://github.com/pascalebeier/hitkeep/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](https://hitkeep.com/reference/configuration/) 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](https://github.com/PascaleBeier/hitkeep/releases/latest) 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](https://hitkeep.com/guides/data/backups-and-restore/) per comandi di ripristino e opzioni S3.

## Pagine correlate

- [Proxy attendibili](https://hitkeep.com/guides/installation/trusted-proxies/) — obbligatori dietro un reverse proxy
- [Riferimento di configurazione](https://hitkeep.com/reference/configuration/)
- [Dati e limiti](https://hitkeep.com/reference/facts-and-limits/)
- [Conservazione dei dati](https://hitkeep.com/guides/data/retention/)

Non vuoi gestire personalmente servizi systemd, aggiornamenti e backup? [Confronta HitKeep Cloud](https://hitkeep.com/it/pricing/) per l’hosting gestito in UE (Francoforte) o negli Stati Uniti (Virginia), con aggiornamenti senza interruzioni e backup automatici.

[Indietro Homebrew](https://hitkeep.com/it/guides/installation/homebrew/)[Avanti Docker Compose](https://hitkeep.com/it/guides/installation/docker-compose/)