---
title: "Exécuter HitKeep avec un seul binaire Linux | HitKeep"
description: "Exécutez HitKeep comme solution d’analyse auto-hébergée à binaire unique sur un serveur Linux, une VM, un Raspberry Pi ou un réseau restreint."
canonical: "https://hitkeep.com/fr/guides/installation/binary/"
---

# 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](https://hitkeep.com/reference/facts-and-limits/). Les binaires Linux actuels font environ 100 Mo.

Docker Compose simplifie une première installation

Si vous préférez bénéficier d’un réseau et de volumes persistants préconfigurés plutôt que de gérer vous-même une unité systemd, utilisez [Docker Compose](https://hitkeep.com/fr/guides/installation/docker-compose/). Si vous ne souhaitez gérer ni serveurs, ni mises à niveau, ni SMTP, ni sauvegardes, choisissez [HitKeep Cloud](https://hitkeep.com/pricing/).

Compatibilité Linux

Les binaires Linux publiés sont compilés sur Ubuntu 22.04 et nécessitent `glibc 2.35+`. Ils sont testés sur :

- Ubuntu 22.04 ou version ultérieure
- Debian 12 ou version ultérieure
- Amazon Linux 2023
- les autres distributions basées sur glibc avec `glibc 2.35+`

Si votre serveur utilise une version plus ancienne de glibc (par exemple Ubuntu 20.04, Debian 11 ou Amazon Linux 2), utilisez plutôt [Docker Compose](https://hitkeep.com/fr/guides/installation/docker-compose/).

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

Ne placez pas les secrets dans la liste des processus

Ne transmettez jamais `HITKEEP_JWT_SECRET` ni les mots de passe SMTP comme options de ligne de commande : tous les utilisateurs peuvent les voir avec `ps aux`. Utilisez plutôt des variables d’environnement ou un fichier d’environnement complémentaire.

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](https://hitkeep.com/reference/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](https://github.com/PascaleBeier/hitkeep/releases/latest) 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](https://hitkeep.com/guides/data/backups-and-restore/) pour les commandes de restauration et les options S3.

## Ressources associées

- [Proxys de confiance](https://hitkeep.com/guides/installation/trusted-proxies/) — requis derrière un proxy inverse
- [Référence de configuration](https://hitkeep.com/reference/configuration/)
- [Caractéristiques et limites](https://hitkeep.com/reference/facts-and-limits/)
- [Conservation des données](https://hitkeep.com/guides/data/retention/)

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

[Précédent Homebrew](https://hitkeep.com/fr/guides/installation/homebrew/)[Suivant Docker Compose](https://hitkeep.com/fr/guides/installation/docker-compose/)