AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
fix(helm): the Helm chart installs and starts with its documented setup (#15774)
Hazem Adeld0dbb5083f71
diff --git a/.github/workflows/helm-chart.yml b/.github/workflows/helm-chart.ymlnew file mode 100644index 00000000000..e2a2ba7627a--- /dev/null+++ b/.github/workflows/helm-chart.yml@@ -0,0 +1,67 @@+name: Helm chart++on:+ workflow_dispatch:+ pull_request:+ branches:+ - main+ paths:+ - 'deploy/activepieces-helm/**'+ - '.github/workflows/helm-chart.yml'++concurrency:+ group: ${{ github.workflow }}-${{ github.ref }}+ cancel-in-progress: true++jobs:+ install:+ runs-on: ubuntu-latest+ timeout-minutes: 20+ defaults:+ run:+ working-directory: deploy/activepieces-helm+ steps:+ - uses: actions/checkout@v5++ - uses: azure/setup-helm@v4++ - name: Lint and render with default values+ run: |+ helm repo add mittwald https://helm.mittwald.de+ helm repo add bitnami https://charts.bitnami.com/bitnami+ helm dependency build+ helm lint .+ helm template ap . | grep -q '^kind: Rollout'+ helm template ap . --api-versions apps/v1/StatefulSet | grep -q '^kind: StatefulSet'+ helm template ap . --set autoscaling.enabled=true --api-versions apps/v1/StatefulSet --api-versions argoproj.io/v1alpha1/Rollout > "$RUNNER_TEMP/rollout.yaml"+ grep -q '^kind: Rollout' "$RUNNER_TEMP/rollout.yaml"+ grep -q 'name: ap-activepieces-preview' "$RUNNER_TEMP/rollout.yaml"+ grep -A2 'scaleTargetRef:' "$RUNNER_TEMP/rollout.yaml" | grep -q 'kind: Rollout'++ - uses: helm/kind-action@v1++ - name: Create connection secrets+ run: |+ kubectl create secret generic activepieces-config-secrets --from-literal=AP_FRONTEND_URL=http://ap-activepieces.default.svc.cluster.local+ kubectl create secret generic activepieces-db-secrets --from-literal=AP_POSTGRES_HOST=ap-postgresql --from-literal=AP_POSTGRES_PORT=5432 --from-literal=AP_POSTGRES_DATABASE=postgres --from-literal=AP_POSTGRES_USERNAME=postgres --from-literal=AP_POSTGRES_PASSWORD=ci-password+ kubectl create secret generic activepieces-redis-secrets --from-literal=AP_REDIS_HOST=ap-redis-master --from-literal=AP_REDIS_PORT=6379 --from-literal=AP_REDIS_PASSWORD=ci-password++ - name: Install+ run: |+ helm install ap . --wait --timeout 10m \+ --set image.tag=latest \+ --set persistence.storageClassName=standard \+ --set postgresql.enabled=true,postgresql.auth.postgresPassword=ci-password \+ --set redis.enabled=true,redis.architecture=standalone,redis.auth.password=ci-password++ - name: Test+ run: |+ kubectl get statefulset ap-activepieces+ helm test ap++ - name: Debug+ if: failure()+ run: |+ kubectl get pods+ kubectl describe pods+ kubectl logs statefulset/ap-activepieces --tail 200 || truediff --git a/.github/workflows/release-self-hosted.yml b/.github/workflows/release-self-hosted.ymlindex 578d6ff59f4..4277b30f0af 100644--- a/.github/workflows/release-self-hosted.yml+++ b/.github/workflows/release-self-hosted.yml@@ -55,6 +55,11 @@ jobs:exit 1fiecho "Release tag base '$TAG_BASE' matches package.json version '$PACKAGE_VERSION'."+ CHART_APP_VERSION="$(sed -n 's/^appVersion: "\(.*\)"/\1/p' deploy/activepieces-helm/Chart.yaml)"+ if [ "$CHART_APP_VERSION" != "$PACKAGE_VERSION" ]; then+ echo "::error::Helm chart appVersion '$CHART_APP_VERSION' does not match package.json version '$PACKAGE_VERSION'. Bump deploy/activepieces-helm/Chart.yaml."+ exit 1+ fi- name: Fail if tag already existsrun: '! docker manifest inspect activepieces/activepieces:${{ inputs.tag }}'@@ -166,8 +171,9 @@ jobs:npm pkg set version="$TAG_BASE"sed -i -E "s|(image: ghcr.io/activepieces/activepieces:)[0-9][0-9a-zA-Z.-]*|\1$TAG|" docker-compose.ymlgrep -q "image: ghcr.io/activepieces/activepieces:$TAG" docker-compose.yml+ sed -i -E "s|^appVersion: .*|appVersion: \"$TAG_BASE\"|" deploy/activepieces-helm/Chart.yamlgit checkout -b "automated/sync-version-$TAG_BASE"- git add package.json docker-compose.yml+ git add package.json docker-compose.yml deploy/activepieces-helm/Chart.yamlgit commit -m "chore(release): sync version to $TAG_BASE after off-cycle release"git push -f origin "automated/sync-version-$TAG_BASE"diff --git a/brain/knowledge/decisions/000040-helm-chart-keys-are-generated-in-cluster-and-user-secrets-override-them.md b/brain/knowledge/decisions/000040-helm-chart-keys-are-generated-in-cluster-and-user-secrets-override-them.mdnew file mode 100644index 00000000000..198fb3c2b37--- /dev/null+++ b/brain/knowledge/decisions/000040-helm-chart-keys-are-generated-in-cluster-and-user-secrets-override-them.md@@ -0,0 +1,21 @@+---+status: accepted+---++# Helm chart keys are generated in-cluster, and user secrets override them++## Decision++The chart gets `AP_ENCRYPTION_KEY` and `AP_JWT_SECRET` from the mittwald `secret-generator` subchart, which fills `<fullname>-secrets` and `<fullname>-jwt-secret` in-cluster. The pod reads them through `envFrom`. A user-created `activepieces-auth-secrets` is mapped through `env`, so it wins at runtime.++## Context++GIT-1923: after worker v2 the generated secrets were never wired in, so a default install crashlooped. Users who worked around it had already created `activepieces-auth-secrets` with their own keys, and their stored data is encrypted with those keys.++## Why++`lookup` + `randAlphaNum` regenerates the key on every `helm template` / ArgoCD render, which would silently rotate the encryption key. Rendering one env name twice to get precedence gets rejected by Helm 4's server-side apply. `env` over `envFrom` gives the runtime fallback without either problem, and upgrades change nothing for existing users.++## Consequences++Renaming the generated keys or secrets orphans every install's key. A user key present at render time is pinned (`optional: false`), so the fallback only ever serves installs that never had their own key. The chart keeps a cluster-scoped operator as a dependency.diff --git a/brain/knowledge/engineering/helm-chart.md b/brain/knowledge/engineering/helm-chart.mdindex f707d1dcdbf..451545e08bd 100644--- a/brain/knowledge/engineering/helm-chart.md+++ b/brain/knowledge/engineering/helm-chart.md@@ -10,15 +10,25 @@ The Kubernetes install we ship to self-hosters, at `deploy/activepieces-helm/`.`templates/deployment.yaml` builds one `env:` list from two values keys, in this fixed order:- **`activepiecesConfig`** — a flat map rendered as plain `value:` entries. Rendered **first**. The shipped default holds only `AP_CONTAINER_TYPE`.-- **`activepiecesEnvVariables`** — a map of *secret name* → *list of var names*, rendered as `secretKeyRef` with `optional: true`. Rendered **second**. The shipped default routes `AP_EDITION`, `AP_EXECUTION_MODE`, `AP_ENCRYPTION_KEY`, `AP_JWT_SECRET` and the queue/auth vars through three secrets the chart does not create.+- **`activepiecesEnvVariables`** — a map of *secret name* → *list of var names*, rendered as `secretKeyRef` with `optional: true`. Rendered **second**. The shipped default routes `AP_EDITION`, `AP_EXECUTION_MODE`, `AP_ENCRYPTION_KEY`, `AP_JWT_SECRET` and the queue/auth vars through secrets the chart does not create.+- **`envFrom` the generated secrets**: lowest precedence. Supplies `AP_ENCRYPTION_KEY` / `AP_JWT_SECRET` when no user secret sets them, because `env` beats `envFrom`.## What the chart creates-Only two secrets, both `data: {}` with mittwald `secret-generator` annotations that fill them in-cluster: `<release>-secrets` (encryption key) and `<release>-jwt-secret`. Postgres and Redis come from the Bitnami subcharts unless disabled.+Only two secrets, both `data: {}` with mittwald `secret-generator` annotations that fill them in-cluster: `<release>-secrets` (`AP_ENCRYPTION_KEY`) and `<release>-jwt-secret` (`AP_JWT_SECRET`). Postgres and Redis come from the Bitnami subcharts (off by default, images from `bitnamilegacy/*`). With `workloadType` unset, the `activepieces.workloadType` helper picks a `StatefulSet` only on a live cluster (kind-level entries like `apps/v1/StatefulSet` in `.Capabilities.APIVersions`) that has no Argo Rollouts and no `<fullname>-preview` Service from an earlier Rollout revision; everything else, including offline renders, stays a `Rollout` as on main.## Key files- `deploy/activepieces-helm` — chart, `values.yaml`, and `templates/`## Gotchas- **Setting the same `AP_*` var in both values keys puts two entries with one name in the pod spec, and the secret wins.** `activepiecesConfig` renders before `activepiecesEnvVariables`, and for duplicate env names the later entry is what the container process sees. Since the shipped `values.yaml` already lists `AP_EDITION` and `AP_EXECUTION_MODE` under `activepieces-config-secrets`, a user who follows the docs *and* has created that secret silently gets the secret's edition, not the one they set. `optional: true` saves the common case — with no such secret the ref is skipped and the plain value survives — so this reads as "works on my cluster" right up until someone populates the secret. Set each variable in exactly one place.-- **`activepieces-config-secrets`, `activepieces-auth-secrets` and `activepieces-queue-secrets` do not exist until you make them, and the script `values.yaml` names for the job is not in the repo.** The comment points at `deploy/scripts/apply-secrets.sh --secret-name <name>`; there is no `deploy/scripts/` directory. Every ref is `optional: true`, so a fresh `helm install` comes up anyway on the app's own defaults — which is why the gap survived: nothing fails, the vars are just quietly absent.+- **The DB and Redis secrets do not exist until you make them.** Every ref is `optional: true`, so a missing secret is silently skipped and the app falls back to its own defaults (e.g. `localhost` Postgres), even with the subcharts enabled.+- **Offline renders can't see the cluster.** Helm's default `.Capabilities.APIVersions` has group/version entries only; a connected install adds kind-level ones such as `apps/v1/StatefulSet`. That is the only live-cluster signal that works with `--create-namespace` and restricted RBAC (a `lookup` sees no namespace yet and errors on Forbidden).+- **A user-owned key is pinned once it exists.** If `AP_ENCRYPTION_KEY` / `AP_JWT_SECRET` are in the user's secret when the chart renders, their `secretKeyRef` becomes `optional: false`, so a deleted secret stops the pod instead of letting the generated fallback key silently take over.+- **Never render one env name twice to get precedence.** Helm 4 installs with server-side apply, which rejects duplicate `env` keys ("duplicate entries for key"). A lower-precedence default has to come through `envFrom`.+- **Removing a duplicate env name on a Helm 3 upgrade deletes both entries.** The strategic merge patch matches `env` items by name ("hides previous definition ... may be dropped when using apply"), so a var set in both values keys vanishes from the live pod spec. Never change how an already-duplicated name renders; fix duplicates in the user's values instead.+- **`AP_FRONTEND_URL` must be reachable from inside the pod.** The worker downloads piece bundles through the public URL, so a `localhost` value boots fine and then fails every flow with `fetch failed`.+- **The mittwald subchart's ClusterRole is named after the release.** Two releases with the same name in different namespaces collide, and deleting a namespace without `helm uninstall` leaves it behind. A second release can set `kubernetes-secret-generator.enabled: false`; the first operator watches every namespace.+- **Helm 4 upgrades of a `Rollout` need `--force-conflicts`.** Argo's controller owns the Service `.spec.selector` (it adds `rollouts-pod-template-hash`), so server-side apply conflicts. After a forced upgrade Argo re-adds the hash and traffic keeps routing.+- **The HPA targets whatever `activepieces.workloadType` resolves to.** It used to target a `Deployment` the chart never creates.+- **`Chart.yaml` `appVersion` is the default image tag.** `release-self-hosted.yml` fails the release if it drifts from `package.json`, and the version sync PR bumps it.- **`AP_EDITION=ee` needs `AP_EXECUTION_MODE` set in the same breath or the pod will not boot.** `system-validator.ts` throws for `cloud`/`ee` in production unless the mode is one of `SANDBOX_PROCESS`, `SANDBOX_CODE_ONLY`, `SANDBOX_CODE_AND_PROCESS`, and the default is `UNSANDBOXED`. The error names the execution mode, not the edition, so it reads as a sandboxing problem rather than the edition switch that caused it.diff --git a/deploy/activepieces-helm/Chart.yaml b/deploy/activepieces-helm/Chart.yamlindex 9b63e2aaf93..6e3d033116a 100644--- a/deploy/activepieces-helm/Chart.yaml+++ b/deploy/activepieces-helm/Chart.yaml@@ -16,13 +16,13 @@ type: application# This is the chart version. This version number should be incremented each time you make changes# to the chart and its templates, including the app version.# Versions are expected to follow Semantic Versioning (https://semver.org/)-version: 0.3.0+version: 0.4.0# This is the version number of the application being deployed. This version number should be# incremented each time you make changes to the application. Versions are not expected to# follow Semantic Versioning. They should reflect the version the application is using.# It is recommended to use it with quotes.-appVersion: "0.71.2"+appVersion: "0.92.0"dependencies:- name: kubernetes-secret-generatordiff --git a/deploy/activepieces-helm/templates/_helpers.tpl b/deploy/activepieces-helm/templates/_helpers.tplindex 14c66b5e843..34d574caff5 100644--- a/deploy/activepieces-helm/templates/_helpers.tpl+++ b/deploy/activepieces-helm/templates/_helpers.tpl@@ -60,3 +60,15 @@ Create the name of the service account to use{{- default "default" .Values.serviceAccount.name }}{{- end }}{{- end }}++{{- define "activepieces.workloadType" -}}+{{- $liveCluster := .Capabilities.APIVersions.Has "apps/v1/StatefulSet" }}+{{- $argoRollouts := .Capabilities.APIVersions.Has "argoproj.io/v1alpha1/Rollout" }}+{{- if .Values.workloadType }}+{{- .Values.workloadType }}+{{- else if and $liveCluster (not $argoRollouts) (not (lookup "v1" "Service" .Release.Namespace (printf "%s-preview" (include "activepieces.fullname" .)))) }}+{{- "statefulset" }}+{{- else }}+{{- "rollout" }}+{{- end }}+{{- end }}diff --git a/deploy/activepieces-helm/templates/deployment.yaml b/deploy/activepieces-helm/templates/deployment.yamlindex e7e2c431733..ecbcb4074ad 100644--- a/deploy/activepieces-helm/templates/deployment.yaml+++ b/deploy/activepieces-helm/templates/deployment.yaml@@ -1,4 +1,4 @@-{{- if eq (.Values.workloadType | default "rollout") "statefulset" }}+{{- if eq (include "activepieces.workloadType" .) "statefulset" }}apiVersion: apps/v1kind: StatefulSet{{- else }}@@ -13,7 +13,7 @@ spec:{{- if not .Values.autoscaling.enabled }}replicas: {{ .Values.replicaCount }}{{- end }}- {{- if eq (.Values.workloadType | default "rollout") "statefulset" }}+ {{- if eq (include "activepieces.workloadType" .) "statefulset" }}serviceName: {{ include "activepieces.fullname" . }}podManagementPolicy: {{ .Values.podManagementPolicy | default "OrderedReady" }}{{- end }}@@ -54,6 +54,11 @@ spec:- name: httpcontainerPort: {{ .Values.container.port }}protocol: TCP+ envFrom:+ - secretRef:+ name: {{ include "activepieces.fullname" . }}-secrets+ - secretRef:+ name: {{ include "activepieces.fullname" . }}-jwt-secret{{- if or .Values.activepiecesEnvVariables .Values.activepiecesConfig }}env:{{- range $key, $value := .Values.activepiecesConfig }}@@ -62,12 +67,16 @@ spec:{{- end }}{{- range $secretName, $vars := .Values.activepiecesEnvVariables }}{{- range $vars }}+ {{- $userOwnedKey := false }}+ {{- if has . (list "AP_ENCRYPTION_KEY" "AP_JWT_SECRET") }}+ {{- $userOwnedKey = hasKey ((lookup "v1" "Secret" $.Release.Namespace $secretName).data | default dict) . }}+ {{- end }}- name: {{ . }}valueFrom:secretKeyRef:name: {{ $secretName | quote }}key: {{ . }}- optional: true+ optional: {{ not $userOwnedKey }}{{- end }}{{- end }}{{- end }}@@ -95,7 +104,7 @@ spec:{{- end }}{{- if or .Values.persistence.enabled .Values.volumes }}volumes:- {{- if and .Values.persistence.enabled (ne (.Values.workloadType | default "rollout") "statefulset") }}+ {{- if and .Values.persistence.enabled (ne (include "activepieces.workloadType" .) "statefulset") }}- name: cachepersistentVolumeClaim:claimName: {{ include "activepieces.fullname" . }}-cache@@ -116,7 +125,7 @@ spec:tolerations:{{- toYaml . | nindent 8 }}{{- end }}- {{- if eq (.Values.workloadType | default "rollout") "statefulset" }}+ {{- if eq (include "activepieces.workloadType" .) "statefulset" }}{{- if .Values.persistence.enabled }}volumeClaimTemplates:- metadata:diff --git a/deploy/activepieces-helm/templates/hpa.yaml b/deploy/activepieces-helm/templates/hpa.yamlindex 20415a405a3..431453f7047 100644--- a/deploy/activepieces-helm/templates/hpa.yaml+++ b/deploy/activepieces-helm/templates/hpa.yaml@@ -7,8 +7,13 @@ metadata:{{- include "activepieces.labels" . | nindent 4 }}spec:scaleTargetRef:+ {{- if eq (include "activepieces.workloadType" .) "statefulset" }}apiVersion: apps/v1- kind: Deployment+ kind: StatefulSet+ {{- else }}+ apiVersion: argoproj.io/v1alpha1+ kind: Rollout+ {{- end }}name: {{ include "activepieces.fullname" . }}minReplicas: {{ .Values.autoscaling.minReplicas }}maxReplicas: {{ .Values.autoscaling.maxReplicas }}diff --git a/deploy/activepieces-helm/templates/pvc.yaml b/deploy/activepieces-helm/templates/pvc.yamlindex f466ab5103d..a03b5a157f3 100644--- a/deploy/activepieces-helm/templates/pvc.yaml+++ b/deploy/activepieces-helm/templates/pvc.yaml@@ -1,4 +1,4 @@-{{- if and .Values.persistence.enabled (ne (.Values.workloadType | default "rollout") "statefulset") }}+{{- if and .Values.persistence.enabled (ne (include "activepieces.workloadType" .) "statefulset") }}apiVersion: v1kind: PersistentVolumeClaimmetadata:diff --git a/deploy/activepieces-helm/templates/secret.yaml b/deploy/activepieces-helm/templates/secret.yamlindex 930c8d8760d..4cfb4cb993e 100644--- a/deploy/activepieces-helm/templates/secret.yaml+++ b/deploy/activepieces-helm/templates/secret.yaml@@ -5,7 +5,7 @@ metadata:labels:{{- include "activepieces.labels" . | nindent 4 }}annotations:- secret-generator.v1.mittwald.de/autogenerate: encryption-key+ secret-generator.v1.mittwald.de/autogenerate: AP_ENCRYPTION_KEYsecret-generator.v1.mittwald.de/encoding: hexsecret-generator.v1.mittwald.de/length: "32"type: Opaque@@ -18,7 +18,7 @@ metadata:labels:{{- include "activepieces.labels" . | nindent 4 }}annotations:- secret-generator.v1.mittwald.de/autogenerate: jwt-secret+ secret-generator.v1.mittwald.de/autogenerate: AP_JWT_SECRETsecret-generator.v1.mittwald.de/length: "64"type: Opaquedata: {}\ No newline at end of filediff --git a/deploy/activepieces-helm/templates/service.yaml b/deploy/activepieces-helm/templates/service.yamlindex d20a62fec79..6713b7a74b5 100644--- a/deploy/activepieces-helm/templates/service.yaml+++ b/deploy/activepieces-helm/templates/service.yaml@@ -17,7 +17,7 @@ spec:name: apiselector:{{- include "activepieces.selectorLabels" . | nindent 4 }}-{{- if ne (.Values.workloadType | default "rollout") "statefulset" }}+{{- if ne (include "activepieces.workloadType" .) "statefulset" }}---apiVersion: v1kind: Servicediff --git a/deploy/activepieces-helm/values.yaml b/deploy/activepieces-helm/values.yamlindex e4b6ff96c34..b574d7965c5 100644--- a/deploy/activepieces-helm/values.yaml+++ b/deploy/activepieces-helm/values.yaml@@ -111,6 +111,11 @@ autoscaling:targetCPUUtilizationPercentage: 80# targetMemoryUtilizationPercentage: 80+rollout:+ blueGreen:+ autoPromotionEnabled: true+ scaleDownDelaySeconds: 30+persistence:enabled: truesize: 2Gi@@ -138,6 +143,8 @@ affinity: {}# ============================================================================postgresql:enabled: false+ image:+ repository: bitnamilegacy/postgresql# auth:# database: activepieces# username: postgres@@ -160,6 +167,8 @@ postgresql:# ============================================================================redis:enabled: false+ image:+ repository: bitnamilegacy/redis# auth:# enabled: true# password: "" # leave empty to auto-generate@@ -175,7 +184,6 @@ activepiecesConfig:# Map of Kubernetes secret name → list of AP_* (and OTEL_*) env var names to inject.# Each var name must exist as a key in the corresponding secret.-# Populate secrets with deploy/scripts/apply-secrets.sh --secret-name <name> before deploying.activepiecesEnvVariables:activepieces-config-secrets:- AP_EDITIONdiff --git a/docs/install/options/helm.mdx b/docs/install/options/helm.mdxindex 2e363b91928..88e349bce38 100644--- a/docs/install/options/helm.mdx+++ b/docs/install/options/helm.mdx@@ -13,87 +13,37 @@ This guide walks you through deploying Activepieces on Kubernetes using the offi- Helm 3.x installed- kubectl configured to access your cluster-## Using External PostgreSQL and Redis+When `helm install` or `helm upgrade` talks to a cluster without [Argo Rollouts](https://argoproj.github.io/rollouts/), the chart deploys a `StatefulSet`; otherwise it deploys an Argo `Rollout`. A release that already runs as a `Rollout` stays one. Rendering without a cluster (`helm template`, Kustomize) produces a `Rollout`, so set `workloadType: statefulset` there, or pass the cluster's API versions as Argo CD does. The StatefulSet volume uses the `local-path` storage class unless you set `persistence.storageClassName`.-The Helm chart supports using external PostgreSQL and Redis services instead of deploying the Bitnami subcharts.+## Database and Redis-### Using External PostgreSQL+The chart reads PostgreSQL and Redis settings from the secrets listed under `activepiecesEnvVariables` in `values.yaml`. Create them before installing:-To use an external PostgreSQL instance:+Put the settings in env files, so passwords stay out of your shell history and process list. Run `umask 077` first so only you can read them:-```yaml-postgresql:- enabled: false # Disable Bitnami PostgreSQL subchart- host: "your-postgres-host.example.com"- port: 5432- useSSL: true # Enable SSL if required- auth:- database: "activepieces"- username: "postgres"- password: "your-password"- # Or use external secret reference:- # externalSecret:- # name: "postgresql-credentials"- # key: "password"+```bash title="db.env"+AP_POSTGRES_HOST=your-postgres-host.example.com+AP_POSTGRES_PORT=5432+AP_POSTGRES_DATABASE=activepieces+AP_POSTGRES_USERNAME=postgres+AP_POSTGRES_PASSWORD=your-password```-Alternatively, you can use a connection URL:--```yaml-postgresql:- enabled: false- url: "postgresql://user:password@host:5432/database?sslmode=require"+```bash title="redis.env"+AP_REDIS_HOST=your-redis-host.example.com+AP_REDIS_PORT=6379+AP_REDIS_PASSWORD=your-password```-### Using External Redis--To use an external Redis instance:--```yaml-redis:- enabled: false # Disable Bitnami Redis subchart- host: "your-redis-host.example.com"- port: 6379- useSSL: false # Enable SSL if required- auth:- enabled: true- password: "your-password"- # Or use external secret reference:- # externalSecret:- # name: "redis-credentials"- # key: "password"-```--Alternatively, you can use a connection URL:--```yaml-redis:- enabled: false- url: "redis://:password@host:6379/0"+```bash+kubectl create secret generic activepieces-db-secrets --from-env-file=db.env+kubectl create secret generic activepieces-redis-secrets --from-env-file=redis.env+rm db.env redis.env```-### External Secret References+To run PostgreSQL and Redis inside the cluster instead, set `postgresql.enabled: true` / `redis.enabled: true`. The hosts are `<release>-postgresql` and `<release>-redis-master`.-For better security, you can reference passwords from existing Kubernetes secrets (useful with External Secrets Operator or Sealed Secrets):--```yaml-postgresql:- enabled: false- host: "your-postgres-host.example.com"- auth:- externalSecret:- name: "postgresql-credentials"- key: "password"--redis:- enabled: false- host: "your-redis-host.example.com"- auth:- enabled: true- externalSecret:- name: "redis-credentials"- key: "password"-```+`AP_JWT_SECRET` and `AP_ENCRYPTION_KEY` are generated on first install. To bring your own, put them in `activepieces-auth-secrets`; that secret takes precedence.## Quick Start@@ -107,7 +57,9 @@ cd activepieces### 2. Install Dependencies```bash-helm dependency update+helm repo add mittwald https://helm.mittwald.de+helm repo add bitnami https://charts.bitnami.com/bitnami+helm dependency build deploy/activepieces-helm```### 3. Create a Values File@@ -115,21 +67,28 @@ helm dependency updateCreate a `my-values.yaml` file with your configuration. You can use the [example values file](https://github.com/activepieces/activepieces/blob/main/deploy/activepieces-helm/values.yaml) as a reference.The Helm chart has sensible defaults for required values while leaving the optional ones empty, but you should customize these core values for production.-Include these so you can activate a [license key](/install/configure-operate/enterprise-license) later:+Set the core settings in the `activepieces-config-secrets` secret the chart already reads. `AP_EDITION` and `AP_EXECUTION_MODE` let you activate a [license key](/install/configure-operate/enterprise-license) later:++```bash+kubectl create secret generic activepieces-config-secrets \+ --from-literal=AP_FRONTEND_URL=https://activepieces.yourdomain.com \+ --from-literal=AP_EDITION=ee \+ --from-literal=AP_EXECUTION_MODE=SANDBOX_CODE_ONLY+```++`AP_FRONTEND_URL` is required, and it must also be reachable from inside the pod: the worker downloads pieces through it.```yaml-activepiecesConfig:- AP_EDITION: "ee"- AP_EXECUTION_MODE: "SANDBOX_CODE_ONLY"+persistence:+ storageClassName: "your-storage-class" # see `kubectl get storageclass````<Warning>-Set both, and set each variable in **one place only**. `activepiecesConfig` writes plain values into the pod, while `activepiecesEnvVariables` pulls the same names from Kubernetes secrets you create yourself and renders *after* it, so a secret that holds the key wins. The chart lists `AP_EDITION` and `AP_EXECUTION_MODE` under `activepieces-config-secrets` by default, so either remove them from there or set them in that secret instead of here.+Set `AP_EDITION` and `AP_EXECUTION_MODE` together: `AP_EDITION=ee` with the default execution mode is rejected at startup and the app will not boot.-`AP_EDITION=ee` with the default execution mode is rejected at startup and the app will not boot.+Set each variable in **one place only**. A name that is both in `activepiecesConfig` and in an `activepiecesEnvVariables` list is rendered twice, which Helm 4 rejects (`duplicate entries for key`).</Warning>-### 4. Install Activepieces```bash@@ -147,7 +106,7 @@ kubectl get services## Production Checklist-- [ ] Set `frontendUrl` to your actual domain+- [ ] Set `AP_FRONTEND_URL` to your actual domain- [ ] Set strong passwords for PostgreSQL and Redis (or keep auto-generated)- [ ] Configure proper ingress with TLS- [ ] Set appropriate resource limits@@ -160,29 +119,35 @@ kubectl get services```bash# Update dependencies-helm dependency update+helm dependency build deploy/activepieces-helm# Upgrade releasehelm upgrade activepieces deploy/activepieces-helm -f my-values.yaml-# Check upgrade status-kubectl rollout status deployment/activepieces+# Check upgrade status (StatefulSet)+kubectl rollout status statefulset/activepieces+# Check upgrade status (Argo Rollout)+kubectl wait --for=jsonpath='{.status.phase}'=Healthy rollout/activepieces --timeout=10m```+With Helm 4 and `workloadType: rollout`, add `--force-conflicts` to `helm upgrade`. Argo Rollouts owns the Service selectors, and Helm 4's server-side apply stops on that conflict otherwise.++The bundled secret generator creates cluster-wide RBAC named after the release, so give each release in a cluster its own name. A second release can also set `kubernetes-secret-generator.enabled: false`, because the first release's generator already serves every namespace.+## Troubleshooting### Common Issues-1. **Pod won't start**: Check logs with `kubectl logs deployment/activepieces`+1. **Pod won't start**: Check logs with `kubectl logs -l app.kubernetes.io/instance=activepieces,app.kubernetes.io/name=activepieces`2. **Database connection**: Verify PostgreSQL credentials and connectivity-3. **Frontend URL**: Ensure `frontendUrl` is accessible from external sources+3. **Frontend URL**: Ensure `AP_FRONTEND_URL` is accessible from external sources4. **Webhooks not working**: Check ingress configuration and DNS resolution### Useful Commands```bash# View logs-kubectl logs deployment/activepieces -f+kubectl logs -l app.kubernetes.io/instance=activepieces,app.kubernetes.io/name=activepieces -f# Port forward for testingkubectl port-forward svc/activepieces 4200:80 --namespace default