---
title: "HitKeep met Helm op Kubernetes implementeren | HitKeep"
description: "Implementeer HitKeep op Kubernetes met de officiële Helm-chart of een StatefulSet en bewaar DuckDB-data, QR-assets, archieven en back-ups op permanente opslag."
canonical: "https://hitkeep.com/nl/guides/installation/kubernetes/"
---

# 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](https://hitkeep.com/guides/tracking/custom-tracking-domains/) 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](https://hitkeep.com/guides/integrations/mcp/) en [AI-modelconfiguratie](https://hitkeep.com/guides/admin/ai-model-configuration/) 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](https://hitkeep.com/guides/installation/trusted-proxies/) 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](https://hitkeep.com/guides/data/s3-backups/) voor voorbeelden.

## Gerelateerd

- [Installatie met Docker Compose](https://hitkeep.com/nl/guides/installation/docker-compose/)
- [Vertrouwde proxy’s](https://hitkeep.com/guides/installation/trusted-proxies/)
- [Back-ups en herstel](https://hitkeep.com/guides/data/backups-and-restore/)
- [S3-back-ups](https://hitkeep.com/guides/data/s3-backups/)
- [Configuratiereferentie](https://hitkeep.com/reference/configuration/)
- [Architectuur](https://hitkeep.com/reference/architecture/)

Draait HitKeep in Kubernetes, maar wil je StatefulSets, PVC’s en clusterupgrades niet beheren? [HitKeep Cloud](https://hitkeep.com/nl/pricing/) beheert de infrastructuur in de beheerde regio die je kiest.

[Vorige Docker Compose](https://hitkeep.com/nl/guides/installation/docker-compose/)[Volgende Trusted proxies](https://hitkeep.com/nl/guides/installation/trusted-proxies/)