Exécuter HitKeep avec un seul binaire Linux

L’installation binaire de HitKeep est la méthode d’auto-hébergement la plus légère : un seul exécutable Linux, DuckDB et NSQ intégrés, sans base de données, cache ni service de file d’attente externe. Choisissez-la pour déployer une solution d’analyse web sur un VPS peu puissant, une machine virtuelle, un Raspberry Pi, un serveur physique ou un réseau restreint où Docker ne convient pas.

HitKeep publie des binaires bruts uniquement pour les serveurs Linux : linux/amd64 et linux/arm64. Téléchargez le fichier correspondant à votre architecture, rendez-le exécutable, puis lancez-le.

Pour connaître la taille vérifiable du binaire, l’utilisation de la mémoire, les limites du stockage, les formats d’exportation et ce qui n’entre pas dans le périmètre du produit, consultez Caractéristiques et limites. Les binaires Linux actuels font environ 100 Mo.

Cibles de compilation prises en charge

Artefact	Cible
`hitkeep-linux-amd64`	Serveurs et machines virtuelles Linux 64 bits
`hitkeep-linux-arm64`	Serveurs Linux ARM64, Raspberry Pi, AWS Graviton, Hetzner CAX
Image Docker	`linux/amd64` et `linux/arm64`

Les binaires bruts sont destinés aux hôtes Linux équipés d’une version récente de glibc. Utilisez Docker Compose si vous avez besoin de l’image de conteneur ou si la distribution hôte est antérieure à la version de référence du binaire.

L’installation binaire convient donc particulièrement :

aux serveurs physiques et machines virtuelles ;
aux environnements réseau restreints ;
aux Raspberry Pi et serveurs ARM (AWS Graviton, Hetzner CAX) ;
aux organisations qui recherchent la surface d’attaque la plus réduite possible.

Démarrage rapide

Télécharger le binaire

Téléchargez la dernière version correspondant à votre architecture depuis 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

Pour un réseau restreint, téléchargez le binaire et SHA256SUMS depuis la page de version GitHub sur une machine connectée à Internet, vérifiez la somme de contrôle, puis transférez le binaire vérifié vers le serveur cible.

Exécuter HitKeep avec systemd

Sur un serveur Linux de production, utilisez systemd afin que HitKeep démarre au lancement du système et redémarre en cas d’échec.

Chaque option possède une variable d’environnement HITKEEP_* équivalente (--public-url ↔ HITKEEP_PUBLIC_URL). Vous pouvez donc tout configurer par l’environnement si vous le souhaitez. L’unité ci-dessous combine les deux formes uniquement pour soustraire les secrets à la ligne de commande visible. La référence de configuration répertorie les deux formes de chaque option.

1. Créez un utilisateur de service dédié et le répertoire de données :

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. Créez /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

Vous pouvez aussi conserver les secrets dans un fichier d’environnement complémentaire, ce qui les tient à l’écart du fichier d’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. Activez et démarrez le service :

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

Vérifier l’installation

Contrôlez la version installée, l’état du service et la disponibilité de la base de données :

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 confirme que le processus est actif. /readyz confirme que la base partagée et toutes les bases d’espace ouvertes sont prêtes.

Publier HitKeep dans un sous-répertoire

La plupart des installations devraient utiliser un nom d’hôte dédié, tel que https://analytics.example.com. Pour publier HitKeep sous un site existant, définissez HITKEEP_PUBLIC_URL sur le chemin externe complet :

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

ou :

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

Le proxy inverse doit transmettre le même préfixe à HitKeep sans le supprimer :

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

Lorsque l’URL publique contient /hitkeep/, le tableau de bord injecte <base href="/hitkeep/" />, les appels d’API restent sous /hitkeep/api/... et le script de suivi peut être installé ainsi :

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

Si les Web Vitals sont activés, hk.js charge https://www.example.net/hitkeep/hk-vitals.js et envoie les mesures à /hitkeep/ingest/web-vitals. Les pages vues et les événements automatiques suivent la même règle pour /hitkeep/ingest et /hitkeep/ingest/event.

En mode préfixé, HitKeep n’expose pas les routes racine /api/..., /hk.js ni les routes de repli du tableau de bord. Les routes locales /healthz et /readyz restent disponibles pour les contrôles du processus, du conteneur et de Kubernetes.

Résolution des problèmes

Échec au démarrage avec `failed to get final advertise address`

Si HitKeep se ferme immédiatement avec le message suivant :

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

la couche de cluster intégrée n’a pas pu déterminer l’adresse IP à annoncer pour le trafic gossip. Cela se produit généralement dans un environnement local ou de développement où l’adresse d’écoute par défaut est 0.0.0.0:7946, mais où l’hôte ne possède pas d’adresse réseau privée détectable.

Pour une instance locale à nœud unique, liez explicitement l’adresse du cluster à l’interface de bouclage :

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

Ou avec une variable d’environnement :

HITKEEP_BIND_ADDR=127.0.0.1:7946 ./hitkeep

Pour un déploiement à plusieurs nœuds, définissez --bind-addr ou HITKEEP_BIND_ADDR sur une véritable adresse privée joignable par les autres nœuds, et non sur l’interface de bouclage.

Mettre à niveau

Lisez les dernières notes de version et effectuez une sauvegarde complète. Téléchargez le nouveau binaire pour la même architecture à l’aide de la commande de démarrage rapide, puis remplacez l’exécutable pendant l’arrêt du service :

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

Conservez l’ancien binaire et la sauvegarde antérieure jusqu’à ce que le contrôle de disponibilité et une requête de suivi réussissent. Consultez les notes de version avant toute rétrogradation : après une migration de données, une ancienne version peut ne plus fonctionner avec les données mises à niveau.

Sauvegarder

Pour un service en cours d’exécution, privilégiez le processus de sauvegarde cohérente intégré à HitKeep. Ajoutez ces entrées à la section [Service] de l’unité ou à un fichier complémentaire systemd, puis redémarrez le service :

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

Pour une copie brute du système de fichiers, arrêtez d’abord HitKeep afin que la base et le WAL ne puissent pas évoluer indépendamment :

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 copie doit inclure le chemin HITKEEP_DB_PATH configuré, toute l’arborescence HITKEEP_DATA_PATH avec les bases des espaces sous tenants/*/hitkeep.db, ainsi que le chemin d’archive à conserver. Consultez Sauvegarde et restauration pour les commandes de restauration et les options S3.

Ressources associées

Proxys de confiance — requis derrière un proxy inverse
Référence de configuration
Caractéristiques et limites
Conservation des données

Vous ne voulez pas gérer vous-même les services systemd, les mises à niveau et les sauvegardes ? Comparez HitKeep Cloud : le binaire est exploité dans la région de votre choix, avec des mises à niveau sans interruption et des sauvegardes automatisées.