HitKeep met Helm op Kubernetes implementeren

Implementeer HitKeep met de officiële Helm-chart in je Kubernetes-cluster wanneer je cluster Helm al gebruikt. De chart maakt een StatefulSet, een ClusterIP Service, een headless Service voor clustering, een optionele Ingress en permanente opslag voor HitKeeps DuckDB-bestanden en lokale assets aan.

Gebruik het gewone manifest verderop op deze pagina als je Helm niet gebruikt of elk Kubernetes-object in één bestand zichtbaar wilt hebben.

Snel aan de slag

Installeren met Helm

De chart wordt als OCI-artefact gepubliceerd in GitHub Container Registry:

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

Maak een namespace en bewaar het JWT-ondertekeningsgeheim voordat je installeert:

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

Sla dit op als 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

Installeer de 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

Laat ingress.enabled op false staan als je cluster geen ingresscontroller heeft en stel de Service beschikbaar via het gebruikelijke patroon van je cluster.

Controleren

Controleer of de rollout van de StatefulSet is voltooid en de persistent volume claim is gekoppeld:

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

Controleer beide probes in een andere terminal terwijl de port-forward actief is:

curl --fail http://localhost:8080/healthz
curl --fail http://localhost:8080/readyz

/healthz bevestigt dat het proces actief is. /readyz bevestigt dat de gedeelde database en elke geopende tenantdatabase gereed zijn.

Te controleren chartwaarden

Waarde	Standaard	Gebruik
image.repository	ghcr.io/pascalebeier/hitkeep	Repository van de containerimage.
image.tag	appversie van de chart, zonder voorloop-v	Overschrijf dit alleen wanneer je bewust een andere appimage dan de chartversie uitvoert.
env.HITKEEP_PUBLIC_URL	http://localhost:8080	Browserzichtbare URL waarop HitKeep bereikbaar is. Stel dit in voor productie.
extraEnv	[]	Door Secrets ondersteunde waarden, zoals HITKEEP_JWT_SECRET, SMTP-inloggegevens, S3-inloggegevens of AI-providertokens.
persistence.enabled	true	Maakt een volume claim template voor de datamap van de StatefulSet aan.
persistence.mountPath	/var/lib/hitkeep/data	Permanente mount die door de onderstaande chartstandaarden wordt gebruikt.
ingress.enabled	false	Maakt een Ingress aan voor de ingresscontroller van je cluster.
customTrackingDomains.enabled	false	Configureert runtime-instellingen voor aangepaste trackingdomeinen.
customTrackingDomains.ingress.enabled	false	Maakt een afzonderlijke tracking-only Ingress voor statische trackinghostnamen.
service.type	ClusterIP	Gebruik LoadBalancer of NodePort alleen wanneer dat bij je cluster past.
replicaCount	1	Stel alleen 2 of meer in wanneer je HitKeep-clustering wilt.

De chart stelt deze paden in, tenzij je ze in env overschrijft:

Omgevingsvariabele	Standaard van de 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

Met deze standaardwaarden bewaart dezelfde PVC de gedeelde DuckDB-database, DuckDB-databases van tenants, grafische QR-codeassets onder assets/qr-codes, archiefbestanden en de optionele lokale spamfiltercache.

Aangepaste trackingdomeinen

De Helm-chart ondersteunt aangepaste trackingdomeinen zonder een ingresscontroller mee te leveren. Gebruik dezelfde dashboardprocedure als bij andere zelfgehoste installaties: voeg het domein toe in Teaminstellingen, publiceer het TXT-eigendomsrecord, laat DNS naar het ingresstarget verwijzen en verifieer zodra TLS gereed is.

Gebruik voor gewone Kubernetes-ingresscontrollers de externe TLS-modus:

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

De chart maakt een aparte tracking-Ingress met een naam die van de Helm-release is afgeleid, bijvoorbeeld hitkeep-tracking. Deze routeert alleen /hk.js, /hk-vitals.js, /ingest, /ingest/event en /ingest/web-vitals naar HitKeep. Dashboard-, API-, auth-, share-, MCP-, QR- en SPA-fallbackroutes maken geen deel uit van die Ingress. HitKeep handhaaft de tracking-only hostgrens ook intern.

Implementeer Caddy voor Caddy on-demand TLS afzonderlijk en bewaar de ask-token in een Kubernetes Secret:

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

Configureer de externe Caddy-listener met ask http://hitkeep.analytics.svc.cluster.local/internal/caddy/on-demand-tls/<token>. Caddy stuurt ?domain= naar die URL voordat een certificaat wordt uitgegeven; HitKeep staat alleen ingeschakelde, via DNS geverifieerde aangepaste trackingdomeinen toe.

Upgraden

Bewaar hitkeep-values.yaml in versiebeheer of je implementatiesysteem. Upgrade de chart en appimage samen door alleen de chartversie te wijzigen:

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

Lees de releaseopmerkingen voordat je tussen featurereleases upgradet, vooral als je optionele integraties zoals MCP, AI-modelconfiguratie, Google Search Console, SMTP of S3-back-ups gebruikt.

Optionele MCP- en AI-configuratie

MCP en productfuncties met AI blijven uitgeschakeld totdat je ze activeert en configureert. Gebruik env voor niet-geheime instellingen en extraEnv voor tokens.

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

Lees Officiële MCP-server en AI-modelconfiguratie voordat je deze functies in productie inschakelt.

Gewoon Kubernetes-manifest

Gebruik dit manifest als je geen Helm gebruikt. Het houdt HitKeeps runtimepaden gelijk aan die van de officiële chart.

Sla het op als 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

Pas het toe:

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

Voeg een Ingress-resource of externe Service toe volgens het gebruikelijke ingresscontroller- of load-balancerpatroon van je cluster.

Health- en readinessprobes

HitKeep biedt twee probe-endpoints voor Kubernetes:

Endpoint	Doel
GET /healthz	Liveness. Het proces is actief.
GET /readyz	Readiness. De gedeelde database en elke momenteel geopende tenantdatabase zijn gezond.

Deze endpoints blijven op de lokale root beschikbaar, ook wanneer HITKEEP_PUBLIC_URL een padprefix bevat.

Tijdens databaseherstel blijft /healthz slagen, zodat kubelet een proces dat veilig herstelwerk uitvoert niet beëindigt. /readyz retourneert 503, Retry-After: 5 en een JSON-reden zoals database_recovering of database_needs_attention. Daardoor wordt de pod uit de service gehaald totdat de database weer gezond is.

Vertrouwde proxy’s

Als je cluster een ingresscontroller zoals nginx-ingress, Traefik of AWS ALB gebruikt, configureer dan vertrouwde proxy-CIDR’s, zodat echte client-IP’s voor analyse en snelheidslimieten worden gebruikt:

env:
  HITKEEP_TRUSTED_PROXIES: "10.0.0.0/8"

Zie Vertrouwde proxy’s voor meer informatie.

Back-up

Maak een back-up van het volledige permanente datapad. Met de standaardwaarden van de Helm-chart en het bovenstaande gewone manifest zijn dit de belangrijke runtimepaden:

• /var/lib/hitkeep/data/hitkeep.db voor gedeelde control-plane-data
• /var/lib/hitkeep/data/tenants/*/hitkeep.db voor analysedata van niet-standaardteams
• /var/lib/hitkeep/data/assets/qr-codes/* voor grafische QR-codeassets
• /var/lib/hitkeep/data/archive voor lokale archiefartefacten
• /var/lib/hitkeep/data/backups als je HITKEEP_BACKUP_PATH op dat lokale pad instelt
• /var/lib/hitkeep/data/recovery voor automatische-herstelbundels en hervatbare markeringen met beperkte toegangsrechten, tenzij je HITKEEP_DB_RECOVERY_PATH overschrijft

Schakel lokale automatische back-upsnapshots op dezelfde PVC zo in:

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

Gebruik voor back-upopslag buiten het cluster een s3://-HITKEEP_BACKUP_PATH en configureer de S3-omgevingsvariabelen in een Kubernetes Secret. Zie S3-back-ups voor voorbeelden.

Gerelateerd

• Installatie met Docker Compose
• Vertrouwde proxy’s
• Back-ups en herstel
• S3-back-ups
• Configuratiereferentie
• Architectuur

Draait HitKeep in Kubernetes, maar wil je StatefulSets, PVC’s en clusterupgrades niet beheren? HitKeep Cloud beheert de infrastructuur in de beheerde regio die je kiest.