buun-stack/charts/ch-ui/README.md

CH-UI

CH-UI is a modern, feature-rich web interface for ClickHouse databases.

TL;DR

helm install ch-ui ./charts/ch-ui \
  --set clickhouse.url="http://clickhouse:8123" \
  --set clickhouse.auth.password="your-password"

Introduction

This chart bootstraps a CH-UI deployment on a Kubernetes cluster using the Helm package manager.

Prerequisites

• Kubernetes 1.19+
• Helm 3.2.0+
• PV provisioner support in the underlying infrastructure (if persistence is needed)
• ClickHouse server accessible from the cluster

Installing the Chart

To install the chart with the release name ch-ui:

helm install ch-ui ./charts/ch-ui

The command deploys CH-UI on the Kubernetes cluster in the default configuration. The Parameters section lists the parameters that can be configured during installation.

Tip

: List all releases using helm list

Uninstalling the Chart

To uninstall/delete the ch-ui deployment:

helm delete ch-ui

The command removes all the Kubernetes components associated with the chart and deletes the release.

Parameters

Global parameters

Name	Description	Value
nameOverride	String to partially override ch-ui.fullname	""
fullnameOverride	String to fully override ch-ui.fullname	""
imagePullSecrets	Global Docker registry secret names as an array	[]

Common parameters

Name	Description	Value
replicaCount	Number of CH-UI replicas to deploy	1
image.repository	CH-UI image repository	ghcr.io/caioricciuti/ch-ui
image.pullPolicy	CH-UI image pull policy	IfNotPresent
image.tag	CH-UI image tag (immutable tags are recommended)	""
serviceAccount.create	Specifies whether a ServiceAccount should be created	true
serviceAccount.automount	Automatically mount a ServiceAccount's API credentials?	true
serviceAccount.annotations	Annotations to add to the service account	{}
serviceAccount.name	The name of the ServiceAccount to use	""
podAnnotations	Annotations for CH-UI pods	{}
podLabels	Extra labels for CH-UI pods	{}
podSecurityContext	Set CH-UI pod's Security Context	{}
securityContext	Set CH-UI container's Security Context	{}

CH-UI Configuration parameters

Name	Description	Value
clickhouse.url	ClickHouse server URL	"http://clickhouse:8123"
clickhouse.auth.username	ClickHouse username	"default"
clickhouse.auth.password	ClickHouse password (ignored if existingSecret is set)	""
clickhouse.auth.existingSecret	Name of existing Secret containing ClickHouse password	""
clickhouse.auth.secretKeys.password	Key in the existing Secret containing the password	"clickhouse-password"
clickhouse.useAdvanced	Enable advanced mode	false
clickhouse.requestTimeout	Request timeout in milliseconds	30000
clickhouse.basePath	Base path for the application	"/"

Exposure parameters

Name	Description	Value
service.type	CH-UI service type	ClusterIP
service.port	CH-UI service HTTP port	80
service.targetPort	CH-UI container port	5521
ingress.enabled	Enable ingress record generation for CH-UI	false
ingress.className	IngressClass that will be be used to implement the Ingress (Kubernetes 1.18+)	""
ingress.annotations	Additional annotations for the Ingress resource	{}
ingress.hosts[0].host	Default host for the ingress record	ch-ui.local
ingress.hosts[0].paths[0].path	Default path for the default host	/
ingress.hosts[0].paths[0].pathType	Ingress path type	ImplementationSpecific
ingress.tls	Enable TLS configuration for the host defined at ingress.hosts[0].host parameter	[]

Resource parameters

Name	Description	Value
resources.limits.cpu	The CPU limits for the CH-UI containers	500m
resources.limits.memory	The memory limits for the CH-UI containers	512Mi
resources.requests.cpu	The requested CPU for the CH-UI containers	100m
resources.requests.memory	The requested memory for the CH-UI containers	128Mi
livenessProbe.httpGet.path	Path for liveness probe	/
livenessProbe.httpGet.port	Port for liveness probe	http
livenessProbe.initialDelaySeconds	Initial delay seconds for liveness probe	30
livenessProbe.timeoutSeconds	Timeout seconds for liveness probe	5
readinessProbe.httpGet.path	Path for readiness probe	/
readinessProbe.httpGet.port	Port for readiness probe	http
readinessProbe.initialDelaySeconds	Initial delay seconds for readiness probe	5
readinessProbe.timeoutSeconds	Timeout seconds for readiness probe	5
autoscaling.enabled	Enable Horizontal POD autoscaling for CH-UI	false
autoscaling.minReplicas	Minimum number of CH-UI replicas	1
autoscaling.maxReplicas	Maximum number of CH-UI replicas	3
autoscaling.targetCPUUtilizationPercentage	Target CPU utilization percentage	80

Additional parameters

Name	Description	Value
extraEnvVars	Array with extra environment variables to add to CH-UI containers	[]
extraEnvVarsCM	Name of existing ConfigMap containing extra env vars for CH-UI containers	""
extraEnvVarsSecret	Name of existing Secret containing extra env vars for CH-UI containers	""
volumes	Optionally specify extra list of additional volumes for the CH-UI pod(s)	[]
volumeMounts	Optionally specify extra list of additional volumeMounts for the CH-UI container(s)	[]
nodeSelector	Node labels for pod assignment	{}
tolerations	Tolerations for pod assignment	[]
affinity	Affinity for pod assignment	{}

Configuration and installation details

Using an existing Secret

Instead of passing the ClickHouse password directly, you can use an existing Kubernetes Secret:

1. Create a Secret with your ClickHouse password:

kubectl create secret generic clickhouse-secret \
  --from-literal=clickhouse-password="your-password"

2. Install the chart using the existing Secret:

helm install ch-ui ./charts/ch-ui \
  --set clickhouse.auth.existingSecret="clickhouse-secret" \
  --set clickhouse.auth.secretKeys.password="clickhouse-password"

Exposing CH-UI

Using Ingress

To expose CH-UI using an Ingress:

helm install ch-ui ./charts/ch-ui \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host="ch-ui.example.com" \
  --set ingress.className="nginx"

Using LoadBalancer

To expose CH-UI using a LoadBalancer service:

helm install ch-ui ./charts/ch-ui \
  --set service.type=LoadBalancer

Using NodePort

To expose CH-UI using a NodePort service:

helm install ch-ui ./charts/ch-ui \
  --set service.type=NodePort

Adding extra environment variables

You can add extra environment variables using extraEnvVars:

helm install ch-ui ./charts/ch-ui \
  --set extraEnvVars[0].name=LOG_LEVEL \
  --set extraEnvVars[0].value=debug

Or by referencing an existing ConfigMap or Secret:

helm install ch-ui ./charts/ch-ui \
  --set extraEnvVarsCM=my-configmap \
  --set extraEnvVarsSecret=my-secret

Examples

Basic installation with password

helm install ch-ui ./charts/ch-ui \
  --set clickhouse.url="http://my-clickhouse:8123" \
  --set clickhouse.auth.username="admin" \
  --set clickhouse.auth.password="secretpassword"

Installation with external ClickHouse and Ingress

helm install ch-ui ./charts/ch-ui \
  --set clickhouse.url="http://clickhouse.example.com:8123" \
  --set clickhouse.auth.existingSecret="clickhouse-credentials" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host="ch-ui.example.com" \
  --set ingress.tls[0].secretName="ch-ui-tls" \
  --set ingress.tls[0].hosts[0]="ch-ui.example.com"

Installation with resource limits

helm install ch-ui ./charts/ch-ui \
  --set resources.requests.memory="256Mi" \
  --set resources.requests.cpu="250m" \
  --set resources.limits.memory="1Gi" \
  --set resources.limits.cpu="1"

Troubleshooting

CH-UI cannot connect to ClickHouse

1. Verify that the ClickHouse URL is correct and accessible from within the cluster:

kubectl run -it --rm debug --image=busybox --restart=Never -- wget -O- http://clickhouse:8123

2. Check the CH-UI logs:

kubectl logs -l app.kubernetes.io/name=ch-ui

3. Verify the credentials are correct by checking the Secret:

kubectl get secret ch-ui-secret -o jsonpath='{.data.clickhouse-password}' | base64 -d

CH-UI is not accessible

1. Check the service is running:

kubectl get svc -l app.kubernetes.io/name=ch-ui

2. For Ingress issues, check the Ingress controller logs and ensure the Ingress resource is created:

kubectl get ingress
kubectl describe ingress ch-ui