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 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 et Configuration des modèles d’IA 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 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 pour des exemples.

Ressources associées

Vous utilisez HitKeep dans Kubernetes sans vouloir gérer StatefulSets, PVC et mises à niveau du cluster ? Comparez HitKeep Cloud : l’infrastructure est prise en charge dans la région gérée de votre choix.