Kubernetes (Helm)

The Helm chart lives in deployment/helm/pipeshub-ai in the pipeshub-ai repository. Its README is the full reference; this page covers the common path.

Prerequisites

Kubernetes 1.24 or later
Helm 3.11 or later
A clone of the pipeshub-ai repository. Run the commands below from its root.
Optional: External Secrets Operator, if you keep secrets in an external store

Pick a preset

Preset (values file)	Use for, and footprint
Local `values-local.yaml`	kind, minikube, k3d, k3s, Docker Desktop. One app pod, one each of MongoDB, Kafka, Redis, Qdrant and Neo4j, ReadWriteOnce storage.
AWS EKS `values-eks.yaml`	Amazon EKS. gp3 volume per database, MongoDB ×3, Redis primary and replica, Qdrant ×3, Neo4j ×1.
Cloud HA `values-cloud.yaml`	GKE, AKS, or any cluster with ReadWriteMany storage. Two app pods with autoscaling. Not for EKS.

For EKS, the repository has a one-command script and a step-by-step guide: Deploy PipesHub on Amazon EKS.

Install

Build the chart dependencies

MongoDB and Redis are vendored in the repository. This packages them locally and needs no registry login.

helm dependency build ./deployment/helm/pipeshub-ai

Install (local preset)

Keep the release name pipeshub-ai so the Service is also named pipeshub-ai.

helm upgrade --install pipeshub-ai ./deployment/helm/pipeshub-ai \
  --namespace pipeshub-local --create-namespace \
  -f ./deployment/helm/pipeshub-ai/values-local.yaml \
  --set secretKey="$(openssl rand -hex 32)" \
  --set mongodb.auth.rootPassword="change-me" \
  --set redis.auth.password="change-me" \
  --set neo4j.auth.password="change-me" \
  --set qdrant.apiKey="$(openssl rand -hex 32)" \
  --set "mongodb.auth.usernames[0]=pipeshub" \
  --set "mongodb.auth.passwords[0]=$(openssl rand -hex 16)" \
  --set "mongodb.auth.databases[0]=pipeshub"

Add --set image.tag=slim for the smaller image, which downloads models on first use. On kind or minikube, load the image into the cluster first (kind load docker-image or minikube image load).

Open the UI

kubectl port-forward -n pipeshub-local svc/pipeshub-ai 3001:3001

Open http://localhost:3001. Port 3001 serves the UI and the API.

deployment/helm/local-setup-kind-cluster.sh creates a kind cluster, loads the image and installs the chart in one go.

Cloud install

For values-cloud.yaml, also set the storage classes, the ingress and the public URL:

helm upgrade --install pipeshub-ai ./deployment/helm/pipeshub-ai \
  --namespace pipeshub --create-namespace \
  -f ./deployment/helm/pipeshub-ai/values-cloud.yaml \
  --set global.storageClass=<block-class> \
  --set persistence.storageClass=<rwx-class> \
  --set ingress.className=<alb|gce|nginx> \
  --set 'ingress.hosts[0].host=pipeshub.example.com' \
  --set 'ingress.hosts[0].paths[0].path=/' \
  --set 'ingress.hosts[0].paths[0].pathType=Prefix' \
  --set config.frontendPublicUrl=https://pipeshub.example.com \
  --set config.allowedOrigins=https://pipeshub.example.com \
  --set secretKey="$(openssl rand -hex 32)" \
  --set qdrant.apiKey="$(openssl rand -hex 32)" \
  --set sandbox.dind.enabled=true

The chart refuses to install with the default coding sandbox (docker) unless it has a Docker daemon. sandbox.dind.enabled=true adds one as a sidecar, which needs a privileged container. Instead, set config.dockerHost to a daemon you run, or set config.sandboxMode=e2b. See Other settings. Also add the database password flags from the local install (mongodb.auth.*, redis.auth.password, neo4j.auth.password) with your own values. Set global.storageClass for the databases and persistence.storageClass for the shared app volume, which must be ReadWriteMany:

GKE: global.storageClass=standard-rwo, persistence.storageClass=filestore-csi
AKS: global.storageClass=managed-csi, persistence.storageClass=azurefile-csi
On-premises: any block storage for global.storageClass, and any ReadWriteMany storage (NFS, CephFS) for persistence.storageClass

The chart refuses to install more than one app replica unless the shared volume is ReadWriteMany. Only port 3001 is exposed through the ingress. If you use OAuth connectors or provider webhooks, also expose port 8088 on a second host and set config.connectorPublicBackend to its public URL. See the chart README for the values.

Required secrets

secretKey encrypts stored configuration. Generate it once and keep it.
qdrant.apiKey has no default. The chart refuses to render without it, and refuses the old shared defaults such as api_key. Generate one with openssl rand -hex 32.
arango.auth.rootPassword may not be root, if you use ArangoDB.

On a later helm upgrade you can leave qdrant.apiKey unset; the chart reuses the key in the release Secret. helm template, --dry-run=client, Argo CD and Flux cannot read the cluster, so they need it every time. The chart can also read secrets from existing Kubernetes Secrets (secretManagement.existingSecrets) or from External Secrets Operator (secretManagement.externalSecrets).

Upgrade

helm upgrade pipeshub-ai ./deployment/helm/pipeshub-ai --reuse-values \
  --set image.tag=<tag>

Before upgrading to 1.0, read Upgrading to 1.0. A release installed without qdrant.apiKey ran with the public default key, and its first upgrade fails until you set a new one. The chart README has a procedure for that change. It stops the app while Qdrant restarts on the new key, so no request fails with the old one.

Other settings

Telemetry: telemetry.collection.enabled: false turns collection off.
Behind an ingress: the client IP is read from one proxy hop when the ingress is enabled. Set trustProxy to change that.
Coding sandbox: config.sandboxMode is docker by default and needs a Docker daemon (sandbox.dind.enabled=true adds one as a sidecar), or set it to e2b. The values-local.yaml preset sets it to local, which runs generated code in the app pod with no container isolation. Use that preset for single-tenant development clusters only.
External Redis: set redis.enabled=false and redis.external.*. See the chart README for standalone and cluster modes.
Any other environment variable: pass it with extraEnv. See Environment variables.

Check before production

Set every password, secretKey and qdrant.apiKey to strong values.
Configure ingress and TLS.
Keep podDisruptionBudget on (the default; values-local.yaml turns it off) and enable networkPolicy only after you have set its rules for your cluster. The defaults allow ingress from a namespace labelled name: ingress-nginx and from pods in the same namespace, and allow TCP egress only to pods in the same namespace, so enabling it as is blocks external model APIs and connectors. Add what you need with networkPolicy.extraEgress, and test traffic in and out before you rely on it.
Test the upgrade in a non-production namespace first.

Welcome to PipesHub

Using PipesHub

System Overview

Authentication

Mail Configuration

Web Search

Custom Instructions

AI Providers

Connectors

Integrations

Agents

Actions

MCP Server

User Management

Deployment

Developer

Additional Resources

Kubernetes (Helm)

Prerequisites

Pick a preset

Install

Cloud install

Required secrets

Upgrade

Other settings

Check before production

​Prerequisites

​Pick a preset

​Install

​Cloud install

​Required secrets

​Upgrade

​Other settings

​Check before production

​Related

Prerequisites

Pick a preset

Install

Cloud install

Required secrets

Upgrade

Other settings

Check before production

Related