fix(hosting): close upgrade gaps found in adversarial review of the ClickHouse chart

Keeps existing self-hosted deployments working without manual steps:

- Default resource requests/limits match the preset the Bitnami subchart
  applied, so the ClickHouse pod doesn't silently become BestEffort.
- nodeSelector, tolerations, and affinity pass through to the StatefulSet
  for deployments that schedule ClickHouse onto dedicated nodes.
- Optional volumePermissions init container fixes data-volume ownership
  on storage without fsGroup support (NFS, hostPath).
- The helm test reads the password from the datastore secret instead of
  the usually-empty values key, and the pinned-password restart checksum
  is omitted when the password is auto-generated.
- Docs cover updating a pinned CLICKHOUSE_IMAGE_TAG to an official tag
  and the GitOps existingClaim step in more detail.

Author: matt-aitken

docs/self-hosting/docker.mdx

@@ -364,6 +364,13 @@ We patch the latest released version line only, so keep an eye on new releases t
 
 You can also lock the versions of the bundled services, for example with `CLICKHOUSE_IMAGE_TAG`. If you do, or if you bring your own ClickHouse via `CLICKHOUSE_URL`, note that Trigger.dev requires ClickHouse 25.8 or newer.
 
+<Note>
+  The bundled ClickHouse now uses the official `clickhouse/clickhouse-server` image. Your existing
+  data volume carries over automatically. If you previously pinned `CLICKHOUSE_IMAGE_TAG` to a
+  Bitnami tag (for example `25.7.5-debian-12-r0`), update it to an official image tag such as
+  `26.2` — Bitnami tags don't exist in the official repository.
+</Note>
+
 <Note>
   Trigger.dev 4.5.0 is the last version we officially support for running v3 (SDK v3) tasks. If
   you still have v3 tasks, pin `TRIGGER_IMAGE_TAG` to exactly `v4.5.0` or [migrate to

docs/self-hosting/kubernetes.mdx

@@ -286,7 +286,14 @@ redis:
   automatically adopts the existing data volume, so no manual migration is needed. If you render
   manifests without cluster access (for example with GitOps tools that use `helm template`), set
   `clickhouse.persistence.existingClaim` to the old PVC name
-  (`data-<release>-clickhouse-shard0-0`) to keep your data.
+  (`data-<release>-clickhouse-shard0-0`) to keep your data — auto-detection can't run there, and
+  skipping this starts ClickHouse on a fresh empty volume.
+</Note>
+
+<Note>
+  On storage that doesn't support `fsGroup` ownership changes (for example NFS or hostPath), set
+  `clickhouse.volumePermissions.enabled: true` so a one-time init container fixes the data
+  volume's ownership for the non-root ClickHouse server.
 </Note>
 
 **Direct configuration:**

hosting/k8s/helm/templates/clickhouse.yaml

@@ -48,7 +48,12 @@ spec:
     metadata:
       annotations:
         checksum/config: {{ printf "%s\n%s" (include "trigger-v4.clickhouse.dataPathsConfig" .) (.Values.clickhouse.configdFiles | toYaml) | sha256sum }}
+        {{- /* Restart on pinned-password changes; when the password is
+               auto-generated it lives in the retained datastore secret and
+               never rotates on upgrade, so there is nothing to hash. */}}
+        {{- if .Values.clickhouse.auth.password }}
         checksum/secret: {{ .Values.clickhouse.auth.password | sha256sum }}
+        {{- end }}
         {{- with .Values.clickhouse.podAnnotations }}
         {{- toYaml . | nindent 8 }}
         {{- end }}
@@ -63,6 +68,19 @@ spec:
       securityContext:
         {{- toYaml . | nindent 8 }}
       {{- end }}
+      {{- if .Values.clickhouse.volumePermissions.enabled }}
+      initContainers:
+        - name: volume-permissions
+          image: "{{ .Values.global.imageRegistry | default .Values.clickhouse.volumePermissions.image.registry }}/{{ .Values.clickhouse.volumePermissions.image.repository }}:{{ .Values.clickhouse.volumePermissions.image.tag }}"
+          imagePullPolicy: {{ .Values.clickhouse.volumePermissions.image.pullPolicy }}
+          command: ["sh", "-c", "chown -R 101:101 /var/lib/clickhouse"]
+          securityContext:
+            runAsUser: 0
+            runAsNonRoot: false
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/clickhouse
+      {{- end }}
       containers:
         - name: clickhouse
           {{- with .Values.clickhouse.securityContext }}
@@ -134,6 +152,18 @@ spec:
               mountPath: /etc/clickhouse-server/config.d/{{ $filename }}
               subPath: {{ $filename }}
             {{- end }}
+      {{- with .Values.clickhouse.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.clickhouse.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.clickhouse.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
       volumes:
         - name: config
           configMap:

hosting/k8s/helm/templates/tests/test-clickhouse.yaml

@@ -12,10 +12,18 @@ spec:
   containers:
     - name: test-clickhouse
       image: curlimages/curl:8.14.1
+      env:
+        - name: CLICKHOUSE_USER
+          value: {{ .Values.clickhouse.auth.username | quote }}
+        - name: CLICKHOUSE_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: {{ .Values.clickhouse.auth.existingSecret | default (include "trigger-v4.datastore.secretName" .) }}
+              key: {{ .Values.clickhouse.auth.existingSecretKey | default "clickhouse-admin-password" }}
       command: ['sh', '-c']
       args:
         - |
           echo "Testing ClickHouse HTTP interface..."
-          curl -f --user "{{ .Values.clickhouse.auth.username }}:{{ .Values.clickhouse.auth.password }}" "http://{{ include "trigger-v4.clickhouse.hostname" . }}:{{ .Values.clickhouse.service.ports.http }}/ping"
+          curl -f --user "$CLICKHOUSE_USER:$CLICKHOUSE_PASSWORD" "http://{{ include "trigger-v4.clickhouse.hostname" . }}:{{ .Values.clickhouse.service.ports.http }}/ping"
           echo "ClickHouse test completed successfully"
-{{- end }}
+{{- end }}

hosting/k8s/helm/values.yaml

@@ -667,6 +667,22 @@ clickhouse:
     runAsUser: 101
     runAsGroup: 101
 
+  # One-time root init container that chowns the data volume to the ClickHouse
+  # uid. Only needed on storage that doesn't support fsGroup ownership changes
+  # (e.g. NFS, hostPath); on such storage a data volume carried over from the
+  # Bitnami-based chart is otherwise unreadable by the non-root server.
+  volumePermissions:
+    enabled: false
+    image:
+      registry: docker.io
+      repository: busybox
+      tag: "1.35"
+      pullPolicy: IfNotPresent
+
+  nodeSelector: {}
+  tolerations: []
+  affinity: {}
+
   service:
     type: ClusterIP
     ports:
@@ -689,9 +705,16 @@ clickhouse:
 
   ## ClickHouse resource requests and limits
   ## ref: http://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/
-  ## ClickHouse can be very resource intensive. Setting explicit limits and
-  ## requests is strongly recommended for production (see values-production-example.yaml).
-  resources: {}
+  ## ClickHouse can be very resource intensive. The defaults below match the
+  ## resource preset the chart previously applied; size them to your workload
+  ## for production (see values-production-example.yaml).
+  resources:
+    requests:
+      cpu: 1000m
+      memory: 3Gi
+    limits:
+      cpu: 3000m
+      memory: 6Gi
 
   livenessProbe:
     enabled: true