---
title: "Déployer HitKeep sur Kubernetes avec Helm | HitKeep"
description: "Déployez HitKeep sur Kubernetes avec le chart Helm officiel ou un StatefulSet, en conservant les données DuckDB, les ressources QR, les archives et les sauvegardes sur un stockage persistant."
canonical: "https://hitkeep.com/fr/guides/installation/kubernetes/"
---

# Déployer HitKeep sur Kubernetes avec Helm

Déployez HitKeep dans votre cluster Kubernetes avec le chart Helm officiel si votre cluster utilise déjà Helm. Le chart crée un StatefulSet, un Service ClusterIP, un Service headless pour la mise en cluster, un Ingress facultatif et un stockage persistant pour les fichiers DuckDB et les ressources locales de HitKeep.

Si vous n’utilisez pas Helm ou souhaitez voir tous les objets Kubernetes dans un seul fichier, utilisez le manifeste brut proposé plus loin sur cette page.

## Démarrage rapide

### Installer avec Helm

Le chart est publié sous forme d’artefact OCI sur GitHub Container Registry :

```
helm show values oci://ghcr.io/pascalebeier/charts/hitkeep --version 2.13.18
```

Créez un espace de noms et enregistrez le secret de signature JWT avant l’installation :

```
kubectl create namespace analytics
kubectl -n analytics create secret generic hitkeep-secrets \
  --from-literal=jwt-secret="$(openssl rand -hex 32)"
```

Enregistrez le contenu suivant dans `hitkeep-values.yaml` :

```
domain: analytics.example.com

ingress:
  enabled: true
  className: ""

persistence:
  enabled: true
  size: 10Gi
  accessMode: ReadWriteOnce

env:
  HITKEEP_PUBLIC_URL: "https://analytics.example.com"

extraEnv:
  - name: HITKEEP_JWT_SECRET
    valueFrom:
      secretKeyRef:
        name: hitkeep-secrets
        key: jwt-secret
```

Installez le chart :

```
helm install hitkeep oci://ghcr.io/pascalebeier/charts/hitkeep --namespace analytics --version 2.13.18 -f hitkeep-values.yaml

kubectl -n analytics rollout status statefulset/hitkeep
```

Si votre cluster ne dispose pas d’un contrôleur d’Ingress, laissez `ingress.enabled` à `false` et exposez le Service selon les pratiques habituelles de votre cluster.

## Vérifier le déploiement

Confirmez que le déploiement du StatefulSet est terminé et que la demande de volume persistant est liée :

```
kubectl -n analytics rollout status statefulset/hitkeep
kubectl -n analytics get pods,pvc
kubectl -n analytics port-forward service/hitkeep 8080:80
```

Pendant l’exécution du transfert de port, contrôlez les deux sondes dans un autre terminal :

```
curl --fail http://localhost:8080/healthz
curl --fail http://localhost: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.

## Valeurs du chart à vérifier

| Valeur | Valeur par défaut | Utilisation |
| --- | --- | --- |
| image.repository | ghcr.io/pascalebeier/hitkeep | Dépôt de l’image de conteneur. |
| image.tag | version de l’application du chart, sans v initial | Ne la remplacez que si vous exécutez volontairement une image d’application différente de la version du chart. |
| env.HITKEEP_PUBLIC_URL | http://localhost:8080 | URL visible dans le navigateur pour accéder à HitKeep. Définissez-la en production. |
| extraEnv | [] | Valeurs provenant de Secrets, telles que HITKEEP_JWT_SECRET, les identifiants SMTP ou S3 et les jetons des fournisseurs d’IA. |
| persistence.enabled | true | Crée un modèle de demande de volume pour le répertoire de données de HitKeep dans le StatefulSet. |
| persistence.mountPath | /var/lib/hitkeep/data | Point de montage persistant utilisé par les valeurs par défaut ci-dessous. |
| ingress.enabled | false | Crée un Ingress pour le contrôleur d’Ingress de votre cluster. |
| customTrackingDomains.enabled | false | Configure les paramètres d’exécution des domaines de suivi personnalisés de HitKeep. |
| customTrackingDomains.ingress.enabled | false | Crée un Ingress distinct, réservé au suivi, pour les noms d’hôte statiques du tracker. |
| service.type | ClusterIP | Utilisez LoadBalancer ou NodePort uniquement si ce choix correspond à votre cluster. |
| replicaCount | 1 | Définissez 2 ou plus uniquement si vous souhaitez mettre HitKeep en cluster. |

Sauf remplacement dans `env`, le chart définit les chemins suivants :

| Variable d’environnement | Valeur par défaut du chart |
| --- | --- |
| HITKEEP_DB_PATH | /var/lib/hitkeep/data/hitkeep.db |
| HITKEEP_DATA_PATH | /var/lib/hitkeep/data |
| HITKEEP_ARCHIVE_PATH | /var/lib/hitkeep/data/archive |
| HITKEEP_SPAM_FILTER_PATH | /var/lib/hitkeep/data/spam-filter.json |

Avec ces valeurs, le même PVC stocke la base DuckDB partagée, les bases DuckDB des espaces, les images de QR Code sous `assets/qr-codes`, les archives et le cache local facultatif du filtre antispam.

## Domaines de suivi personnalisés

Le chart Helm prend en charge les [domaines de suivi personnalisés](https://hitkeep.com/guides/tracking/custom-tracking-domains/) sans fournir de contrôleur d’Ingress. Suivez la même procédure dans le tableau de bord que pour les autres installations auto-hébergées : ajoutez le domaine dans les paramètres de l’équipe, publiez l’enregistrement TXT de propriété, faites pointer le DNS vers la cible de l’Ingress, puis vérifiez le domaine une fois TLS prêt.

Avec un contrôleur d’Ingress Kubernetes classique, utilisez le mode TLS externe :

```
customTrackingDomains:
  enabled: true
  tlsMode: external
  # Empty defaults to the host from env.HITKEEP_PUBLIC_URL.
  # Set this when tracker domains point at a separate ingress hostname or IP.
  dnsTarget: ""
  ingress:
    enabled: true
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
      - host: tracker.customer-one.example
      - host: tracker.customer-two.example
    tls:
      - hosts:
          - tracker.customer-one.example
          - tracker.customer-two.example
        secretName: hitkeep-tracking-tls
```

Le chart produit un Ingress de suivi distinct nommé d’après la version Helm, par exemple `hitkeep-tracking`. Il ne route vers HitKeep que `/hk.js`, `/hk-vitals.js`, `/ingest`, `/ingest/event` et `/ingest/web-vitals`. Les routes du tableau de bord, de l’API, de l’authentification, du partage, de MCP, des QR Codes et du repli SPA n’en font pas partie. HitKeep impose également cette séparation des hôtes en interne.

Pour le TLS à la demande de Caddy, déployez Caddy séparément et conservez le jeton de vérification dans un Secret Kubernetes :

```
kubectl -n analytics create secret generic hitkeep-caddy-ask \
  --from-literal=token="$(openssl rand -hex 32)"
```

```
customTrackingDomains:
  enabled: true
  tlsMode: caddy-on-demand
  caddyAskToken:
    existingSecret: hitkeep-caddy-ask
    existingSecretKey: token
  ingress:
    enabled: false
```

Configurez le listener Caddy externe avec `ask http://hitkeep.analytics.svc.cluster.local/internal/caddy/on-demand-tls/<token>`. Caddy envoie `?domain=` à cette URL avant d’émettre un certificat, et HitKeep n’autorise que les domaines de suivi personnalisés actifs dont le DNS a été vérifié.

## Mettre à niveau

Conservez `hitkeep-values.yaml` dans votre gestionnaire de sources ou votre système de déploiement. Mettez simultanément à niveau le chart et l’image de l’application en ne modifiant que la version du chart :

```
helm upgrade hitkeep oci://ghcr.io/pascalebeier/charts/hitkeep --namespace analytics --version 2.13.18 -f hitkeep-values.yaml

kubectl -n analytics rollout status statefulset/hitkeep
```

Consultez les notes de version avant toute mise à niveau entre versions fonctionnelles, notamment si vous utilisez des intégrations facultatives comme MCP, la configuration d’un modèle d’IA, Google Search Console, SMTP ou les sauvegardes S3.

## Configuration facultative de MCP et de l’IA

MCP et les fonctionnalités du produit reposant sur l’IA restent désactivés tant que vous ne les activez et ne les configurez pas. Utilisez `env` pour les paramètres non sensibles et `extraEnv` pour les jetons.

```
env:
  HITKEEP_MCP_ENABLED: "true"
  HITKEEP_MCP_PATH: "/mcp"
  HITKEEP_MCP_MAX_RANGE_DAYS: "366"
  HITKEEP_AI_ENABLED: "true"
  HITKEEP_AI_PROVIDER: "openai-compatible"
  HITKEEP_AI_MODEL: "opportunities-json"

extraEnv:
  - name: HITKEEP_AI_API_KEY
    valueFrom:
      secretKeyRef:
        name: hitkeep-ai
        key: api-key
```

Consultez [Serveur MCP officiel](https://hitkeep.com/guides/integrations/mcp/) et [Configuration des modèles d’IA](https://hitkeep.com/guides/admin/ai-model-configuration/) avant d’activer ces fonctions en production.

## Manifeste Kubernetes brut

Utilisez ce manifeste si vous n’employez pas Helm. Il conserve les mêmes chemins d’exécution que le chart officiel.

Enregistrez-le sous `hitkeep.yaml` :

```
apiVersion: v1
kind: Namespace
metadata:
name: analytics
---
apiVersion: v1
kind: Secret
metadata:
name: hitkeep-secrets
namespace: analytics
type: Opaque
stringData:
jwt-secret: "change-me-to-a-long-random-string"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: hitkeep-data
namespace: analytics
spec:
accessModes: ["ReadWriteOnce"]
resources:
  requests:
    storage: 10Gi
---
apiVersion: v1
kind: Service
metadata:
name: hitkeep-headless
namespace: analytics
spec:
clusterIP: None
publishNotReadyAddresses: true
selector:
  app: hitkeep
ports:
  - name: gossip-tcp
    port: 7946
    protocol: TCP
    targetPort: gossip-tcp
  - name: gossip-udp
    port: 7946
    protocol: UDP
    targetPort: gossip-udp
---
apiVersion: v1
kind: Service
metadata:
name: hitkeep
namespace: analytics
spec:
type: ClusterIP
selector:
  app: hitkeep
ports:
  - name: http
    protocol: TCP
    port: 80
    targetPort: http
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: hitkeep
namespace: analytics
spec:
serviceName: hitkeep-headless
replicas: 1
selector:
  matchLabels:
    app: hitkeep
template:
  metadata:
    labels:
      app: hitkeep
  spec:
    securityContext:
      runAsNonRoot: true
      runAsUser: 65532
      runAsGroup: 65532
      fsGroup: 65532
    containers:
      - name: hitkeep
        image: ghcr.io/pascalebeier/hitkeep:2.13.18
        imagePullPolicy: IfNotPresent
        ports:
          - containerPort: 8080
            name: http
          - containerPort: 7946
            name: gossip-tcp
            protocol: TCP
          - containerPort: 7946
            name: gossip-udp
            protocol: UDP
        env:
          - name: HITKEEP_HTTP_ADDR
            value: ":8080"
          - name: HITKEEP_PUBLIC_URL
            value: "https://analytics.example.com"
          - name: HITKEEP_DB_PATH
            value: "/var/lib/hitkeep/data/hitkeep.db"
          - name: HITKEEP_DATA_PATH
            value: "/var/lib/hitkeep/data"
          - name: HITKEEP_ARCHIVE_PATH
            value: "/var/lib/hitkeep/data/archive"
          - name: HITKEEP_SPAM_FILTER_PATH
            value: "/var/lib/hitkeep/data/spam-filter.json"
          - name: HITKEEP_JWT_SECRET
            valueFrom:
              secretKeyRef:
                name: hitkeep-secrets
                key: jwt-secret
        volumeMounts:
          - mountPath: /var/lib/hitkeep/data
            name: data
        livenessProbe:
          httpGet:
            path: /healthz
            port: http
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /readyz
            port: http
          initialDelaySeconds: 5
          periodSeconds: 10
    volumes:
      - name: data
        persistentVolumeClaim:
          claimName: hitkeep-data
```

Appliquez-le :

```
kubectl apply -f hitkeep.yaml
kubectl -n analytics rollout status statefulset/hitkeep
```

Ajoutez votre ressource Ingress ou votre Service externe selon les pratiques habituelles du contrôleur d’Ingress ou du répartiteur de charge de votre cluster.

## Sondes d’état et de disponibilité

HitKeep expose deux points de terminaison pour les sondes Kubernetes :

| Point de terminaison | Rôle |
| --- | --- |
| GET /healthz | État. Le processus est en cours d’exécution. |
| GET /readyz | Disponibilité. La base partagée et toutes les bases d’espace actuellement ouvertes sont saines. |

Ces points de terminaison restent disponibles à la racine locale, même si `HITKEEP_PUBLIC_URL` contient un préfixe de chemin.

Pendant la récupération d’une base de données, `/healthz` reste positif afin que le kubelet n’interrompe pas un processus effectuant une récupération sûre. `/readyz` renvoie `503`, `Retry-After: 5` et un motif JSON tel que `database_recovering` ou `database_needs_attention`, ce qui retire le pod du service jusqu’au rétablissement de la base.

## Proxys de confiance

Si votre cluster utilise un contrôleur d’Ingress comme nginx-ingress, Traefik ou AWS ALB, configurez les plages CIDR des proxys de confiance afin d’utiliser les véritables adresses IP clientes pour l’analyse et la limitation de débit :

```
env:
  HITKEEP_TRUSTED_PROXIES: "10.0.0.0/8"
```

Consultez [Proxys de confiance](https://hitkeep.com/guides/installation/trusted-proxies/) pour plus de détails.

## Sauvegarder

Sauvegardez l’intégralité du chemin de données persistant. Avec les valeurs par défaut du chart Helm et le manifeste brut ci-dessus, les chemins d’exécution importants sont :

- `/var/lib/hitkeep/data/hitkeep.db` pour les données partagées du plan de contrôle ;
- `/var/lib/hitkeep/data/tenants/*/hitkeep.db` pour les données d’analyse des équipes autres que celle par défaut ;
- `/var/lib/hitkeep/data/assets/qr-codes/*` pour les images de QR Code ;
- `/var/lib/hitkeep/data/archive` pour les archives locales ;
- `/var/lib/hitkeep/data/backups` si vous définissez `HITKEEP_BACKUP_PATH` sur ce chemin local ;
- `/var/lib/hitkeep/data/recovery` pour les paquets de récupération automatique et les marqueurs de reprise aux permissions restreintes, sauf remplacement de `HITKEEP_DB_RECOVERY_PATH`.

Pour activer des instantanés de sauvegarde automatiques sur le même PVC :

```
env:
  HITKEEP_BACKUP_PATH: "/var/lib/hitkeep/data/backups"
  HITKEEP_BACKUP_INTERVAL: "60"
  HITKEEP_BACKUP_RETENTION: "24"
```

Pour stocker les sauvegardes hors du cluster, utilisez un chemin `HITKEEP_BACKUP_PATH` en `s3://` et configurez les variables d’environnement S3 dans un Secret Kubernetes. Consultez [Sauvegardes S3](https://hitkeep.com/guides/data/s3-backups/) pour des exemples.

## Ressources associées

- [Installation avec Docker Compose](https://hitkeep.com/fr/guides/installation/docker-compose/)
- [Proxys de confiance](https://hitkeep.com/guides/installation/trusted-proxies/)
- [Sauvegarde et restauration](https://hitkeep.com/guides/data/backups-and-restore/)
- [Sauvegardes S3](https://hitkeep.com/guides/data/s3-backups/)
- [Référence de configuration](https://hitkeep.com/reference/configuration/)
- [Architecture](https://hitkeep.com/reference/architecture/)

Vous utilisez HitKeep dans Kubernetes sans vouloir gérer StatefulSets, PVC et mises à niveau du cluster ? [Comparez HitKeep Cloud](https://hitkeep.com/fr/pricing/) : l’infrastructure est prise en charge dans la région gérée de votre choix.

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