Langfuse

Overview

Langfuse is an open-source LLM observability and evaluation platform: traces, prompt management, evaluations, and a playground. This template deploys the full self-hosted stack — the web app, a background worker, and the three datastores Langfuse requires — with trace data landing in an object store you own. The instance is closed by default. Self-service registration is off, and the owner account is provisioned at boot from a secret you create, so a public endpoint does not hand a stranger an account.

This template deploys into an existing GVC that you already have. It does not create, provision, or manage a GVC. Every workload below runs in each location of that GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-langfuse-web`	Langfuse UI and public API on port `3000` (stateful, autoscales 2–5 replicas on CPU)	—
Workload	`RELEASE_NAME-langfuse-worker`	Trace ingestion, evaluations and integrations (stateful, 1 replica)	—
Workload	`RELEASE_NAME-postgres`	PostgreSQL from the postgres template: users, projects, API keys, prompts, datasets, eval configs (stateful, 1 replica, port `5432`)	—
Workload	`RELEASE_NAME-langfuse-redis`	BullMQ ingestion queue and API key / prompt cache (stateful, 1 replica, port `6379`)	—
Workload	`RELEASE_NAME-langfuse-clickhouse`	Traces, observations and scores; powers the dashboards (stateful, 1 replica, ports `8123` HTTP and `9000` native)	—
Workload	`RELEASE_NAME-postgres-backup`	Scheduled `pg_dumpall` of the bundled PostgreSQL to a bucket (cron)	`postgres.backup.enabled: true`
Volume set	`RELEASE_NAME-pg-vs`	PostgreSQL data	—
Volume set	`RELEASE_NAME-langfuse-redis-vs`	Redis append-only file	—
Volume set	`RELEASE_NAME-langfuse-clickhouse-vs`	ClickHouse local metadata only — data parts live in your bucket	—
Secret	`RELEASE_NAME-langfuse-clickhouse-startup`	ClickHouse startup script (opaque)	—
Secret	`RELEASE_NAME-langfuse-clickhouse-storage`	ClickHouse S3 / GCS disk configuration (opaque)	—
Identity	`RELEASE_NAME-langfuse-identity`	Identity of the web, worker, Redis and ClickHouse workloads; linked to your AWS cloud account on the `aws` path	—
Policy	`RELEASE_NAME-langfuse-policy`	Grants that identity `reveal` on the chart’s secrets and on the prerequisite secrets you name	—
Identity	`RELEASE_NAME-pg-identity`	Identity of the bundled PostgreSQL	—
Policy	`RELEASE_NAME-pg-policy`	Grants PostgreSQL `reveal` on its own credentials secret	—

One bucket serves both ClickHouse (prefix clickhouse/) and Langfuse (prefixes events/ and media/). The auth secret, the database, Redis and ClickHouse credentials secrets and, on GCS, the storage credentials secret are prerequisite secrets you create yourself: the chart references them by name and never creates, modifies, or deletes them.

Prerequisites

Three things must exist before you install: the auth secret, the datastore credentials secrets, and the object storage that traces are written to.

Create the auth secret

A dictionary secret holding five keys. It carries the key material that signs sessions and encrypts stored provider credentials, plus the login for the owner account the template provisions at boot.

cpln secret create-dictionary --name AUTH_SECRET_NAME \
  --entry nextAuthSecret="$(openssl rand -base64 32)" \
  --entry encryptionKey="$(openssl rand -hex 32)" \
  --entry salt="$(openssl rand -base64 32)" \
  --entry adminEmail="you@example.com" \
  --entry adminPassword="$(openssl rand -base64 18)"

Every key is required and the names are exact:

Key	What it does
`nextAuthSecret`	Signs session tokens. Anyone holding it can forge a signed-in session.
`encryptionKey`	Encrypts the LLM provider API keys your users store in Langfuse. Must be exactly 64 hex characters. It cannot be rotated — changing it makes every stored provider key unreadable.
`salt`	Hashes Langfuse’s own API keys.
`adminEmail`	The owner account provisioned at boot. This is how you first sign in.
`adminPassword`	Its password, 8 characters minimum. Record it; it is shown nowhere.

Use three different random values for nextAuthSecret, encryptionKey and salt, and keep a copy of encryptionKey outside Control Plane. Read the values back later with cpln secret reveal AUTH_SECRET_NAME -o yaml.Set langfuse.auth.secretName to this name.

Create the database credentials secret

A dictionary secret with the keys username, password and database. The bundled PostgreSQL initializes with it and Langfuse connects with it:

cpln secret create-dictionary --name DB_CREDENTIALS_SECRET_NAME \
  --entry username=langfuse \
  --entry password="$(openssl rand -hex 24)" \
  --entry database=langfuse

Set postgres.config.credentialsSecretName to this name. Keep all three values URL-safe (letters, digits, -, _): Langfuse puts them in its connection URL. PostgreSQL reads the secret only when its data directory is first initialized; to change the password later, see Rotating Credentials.

Create the Redis and ClickHouse credentials secrets

One dictionary secret per datastore. Both datastores and both Langfuse workloads read them at every start:

cpln secret create-dictionary --name REDIS_SECRET_NAME \
  --entry password="$(openssl rand -hex 24)"

cpln secret create-dictionary --name CLICKHOUSE_SECRET_NAME \
  --entry username=default \
  --entry password="$(openssl rand -hex 24)"

Set redis.credentialsSecretName and clickhouse.credentialsSecretName to those names. Keep the ClickHouse values URL-safe (letters, digits, -, _; the username must also start with a letter): Langfuse puts them in its migration URL.

Set up object storage

Pick one provider. ClickHouse and Langfuse share the bucket under separate prefixes.

AWS S3
Google Cloud Storage

Create an S3 bucket. Set objectStore.aws.bucket to its name and objectStore.aws.region to its region.
If you do not have one, create a Cloud Account for your AWS account and set objectStore.aws.cloudAccountName to its name. The workloads then reach the bucket keylessly.
Create an IAM policy with the JSON below (replace YOUR_BUCKET_NAME) and set objectStore.aws.policyName to its name.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion",
                "s3:GetBucketLocation",
                "s3:AbortMultipartUpload",
                "s3:ListBucketMultipartUploads",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

Langfuse and ClickHouse reach GCS over its S3-compatible endpoint, so this path uses an HMAC key pair held in a second prerequisite secret rather than a Cloud Account.

Create a GCS bucket and set objectStore.gcp.bucket to its name. Set objectStore.provider to gcp.
Create a service account, grant it roles/storage.objectAdmin, and create an HMAC key for it. In the console the same key lives under Cloud Storage → Settings → Interoperability.

gcloud config set project YOUR_PROJECT_ID

gcloud storage buckets create gs://YOUR_BUCKET_NAME

gcloud iam service-accounts create langfuse-storage

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
  --member="serviceAccount:langfuse-storage@$(gcloud config get-value project).iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gcloud storage hmac create langfuse-storage@$(gcloud config get-value project).iam.gserviceaccount.com

Put the pair in a dictionary secret and set objectStore.gcp.credentialsSecretName to its name. The pair never passes through Helm values.

cpln secret create-dictionary --name GCS_CREDENTIALS_SECRET_NAME \
  --entry accessKeyId="YOUR_HMAC_ACCESS_ID" \
  --entry secretAccessKey="YOUR_HMAC_SECRET"

A missing prerequisite secret wedges the deployment instead of failing it. cpln helm install reports success, but the workloads that read the missing secret never start and cpln logs returns nothing. The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-langfuse-web --gvc GVC_NAME -o yaml

Create the secret, and the deployment recovers on its own after a few minutes — or run cpln workload force-redeployment RELEASE_NAME-langfuse-web --gvc GVC_NAME to skip the wait.

Backing up the bundled PostgreSQL to a bucket is optional and needs its own bucket-scoped access; see Backing Up.

Installation

Install from the marketplace registry, naming your auth secret, your three datastore credentials secrets and your bucket:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/langfuse \
  --version 2.0.0 --gvc GVC_NAME \
  --set langfuse.auth.secretName=AUTH_SECRET_NAME \
  --set postgres.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME \
  --set redis.credentialsSecretName=REDIS_SECRET_NAME \
  --set clickhouse.credentialsSecretName=CLICKHOUSE_SECRET_NAME \
  --set objectStore.aws.bucket=YOUR_BUCKET_NAME \
  --set objectStore.aws.region=us-east-1 \
  --set objectStore.aws.cloudAccountName=YOUR_CLOUD_ACCOUNT_NAME \
  --set objectStore.aws.policyName=YOUR_IAM_POLICY_NAME

On the GCS path replace the four objectStore.aws.* values with objectStore.provider=gcp, objectStore.gcp.bucket and objectStore.gcp.credentialsSecretName.

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Object Store

objectStore:
  provider: aws # Options: aws, gcp
  aws:
    bucket: my-langfuse-bucket
    region: us-east-1
    cloudAccountName: my-langfuse-cloudaccount # Control Plane Cloud Account — keyless S3 access
    policyName: my-langfuse-policy # pre-created AWS IAM policy scoped to the bucket above
  gcp:
    bucket: my-langfuse-bucket
    credentialsSecretName: my-langfuse-gcs-credentials # REQUIRED prerequisite dictionary secret when provider is gcp: accessKeyId, secretAccessKey

Only the block matching objectStore.provider is rendered into the workloads; the other is ignored.

langfuse:
  publicUrl: "" # custom domain WITH scheme, e.g. https://langfuse.example.com; empty = the platform canonical endpoint

  web:
    image: langfuse/langfuse:4.70.1 # 4.70.1 or newer: the chart refuses older tags (Critical CVEs)
    minReplicas: 2 # Keep at 2+ for zero-downtime rolling deploys
    maxReplicas: 5
    resources:
      minCpu: 500m
      maxCpu: 1000m
      minMemory: 1Gi
      maxMemory: 2Gi

  worker:
    image: langfuse/langfuse-worker:4.70.1 # 4.70.1 or newer, same as the web image
    replicas: 1
    resources:
      minCpu: 250m
      maxCpu: 500m
      minMemory: 512Mi
      maxMemory: 1Gi

  auth:
    secretName: my-langfuse-auth # REQUIRED prerequisite dictionary secret — create it BEFORE installing (see Prerequisites)
    disableSignup: true # false opens self-service registration to anyone who can reach the UI
    organizationName: Langfuse # organization created for the first-run admin
  migration: # keep the defaults on a fresh install; see "Upgrading from 1.3.0"
    writeMode: events_only # events_only (v4 default) | dual (old + new tables) | legacy (v3 behaviour)
    historicBackfill: true # copy traces stored before the upgrade into the v4 tables; must be false with legacy

langfuse.publicUrl is the origin the browser uses: auth redirects, the pages NextAuth renders server-side, and whether the session cookie gets the Secure flag all derive from it. Leave it empty unless you serve Langfuse on a custom domain, and when you set it include the scheme — a value without one is rejected at render. With langfuse.auth.disableSignup: true (the default) the owner account from your auth secret is the only way in: Langfuse blocks both email/password sign-up and first-time SSO user creation, so the template provisions that account at boot using Langfuse’s headless initialization. Set it to false and anyone who can reach the UI can create an account and their own organization.

Access

publicAccess:
  enabled: true # false keeps the UI reachable only from inside the GVC
internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

These apply to the web tier only; the datastores are never reachable from outside the GVC. A firewall change takes up to a couple of minutes to take effect. With publicAccess.enabled: false the API stays reachable from other workloads in the GVC, but there is no browser path to the UI: cpln port-forward does not reach the Langfuse web tier, so keep public access on if you need to sign in.

PostgreSQL

postgres:
  image: postgres:18
  resources:
    minCpu: 250m
    maxCpu: 1
    minMemory: 512Mi
    maxMemory: 1Gi
  config:
    credentialsSecretName: my-langfuse-db-credentials # PREREQUISITE dictionary secret (username, password, database) — must exist BEFORE install
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

Every knob of the postgres template is available under postgres.*, including scheduled backups — see Backing Up.

Redis

redis:
  image: redis:7.4
  resources:
    minCpu: 100m
    maxCpu: 400m
    minMemory: 256Mi
    maxMemory: 512Mi
  credentialsSecretName: my-langfuse-redis # PREREQUISITE dictionary secret (password) — must exist BEFORE install
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

ClickHouse

clickhouse:
  image: clickhouse/clickhouse-server:26.8 # Langfuse 4 needs 25.12 or newer; the chart refuses older tags
  resources:
    minCpu: 1
    maxCpu: 2
    minMemory: 2Gi
    maxMemory: 4Gi
  credentialsSecretName: my-langfuse-clickhouse # PREREQUISITE dictionary secret (username, password) — must exist BEFORE install
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

The three datastore credentials come from the prerequisite secrets you created; none of them is a Helm value.

Connecting

What	Address	Notes
Web UI and public API	`status.canonicalEndpoint` of `RELEASE_NAME-langfuse-web`	Only when `publicAccess.enabled: true`. Read it with `cpln workload get RELEASE_NAME-langfuse-web --gvc GVC_NAME -o yaml`.
Internal HTTP	`http://RELEASE_NAME-langfuse-web.GVC_NAME.cpln.local:3000`	From other workloads in the GVC, per `internalAccess`.
Health check	`/api/public/health` on either address	Returns `{"status":"OK","version":"..."}`.
First login	`adminEmail` / `adminPassword`	From your auth secret: `cpln secret reveal AUTH_SECRET_NAME -o yaml`.
Langfuse API keys	Settings → API Keys in the UI	Per project, a public / secret key pair.
PostgreSQL	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	Internal only. `username` / `password` / `database` from your `postgres.config.credentialsSecretName` secret.
Redis	`RELEASE_NAME-langfuse-redis.GVC_NAME.cpln.local:6379`	Internal only. `password` from your `redis.credentialsSecretName` secret.
ClickHouse	`RELEASE_NAME-langfuse-clickhouse.GVC_NAME.cpln.local:8123` (HTTP) and `:9000` (native)	Internal only. `username` / `password` from your `clickhouse.credentialsSecretName` secret.

Langfuse 4 ingests traces over OpenTelemetry. Send a first trace with a project key pair:

NOW=$(date +%s)
curl -X POST https://YOUR_LANGFUSE_ENDPOINT/api/public/otel/v1/traces \
  -H "Content-Type: application/json" \
  -H "x-langfuse-ingestion-version: 4" \
  -u "YOUR_PUBLIC_KEY:YOUR_SECRET_KEY" \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"my-app"}}]},
       "scopeSpans":[{"scope":{"name":"curl"},"spans":[{"traceId":"0123456789abcdef0123456789abcdef",
       "spanId":"0123456789abcdef","name":"my-first-trace","kind":1,
       "startTimeUnixNano":"'"$NOW"'000000000","endTimeUnixNano":"'"$NOW"'500000000",
       "attributes":[{"key":"langfuse.observation.input","value":{"stringValue":"Hello"}},
                     {"key":"langfuse.observation.output","value":{"stringValue":"Hello back"}}]}]}]}]}'

Or use a Langfuse SDK: Python SDK v4 or newer, or JS/TS SDK v5 or newer. Verify the web tier is serving once cpln workload get-deployments RELEASE_NAME-langfuse-web --gvc GVC_NAME -o yaml reports it ready:

curl https://YOUR_LANGFUSE_ENDPOINT/api/public/health

First Run

Open the canonical endpoint in a browser and sign in with the adminEmail and adminPassword from your auth secret. The account is an OWNER of the organization named by langfuse.auth.organizationName, which already exists.
Create a project, then generate a key pair under Settings → API Keys.
Send a first trace with the public ingestion API, or point a Langfuse SDK at your endpoint with the same keys:

curl -X POST https://YOUR_LANGFUSE_ENDPOINT/api/public/ingestion \
  -H "Content-Type: application/json" \
  -u "YOUR_PUBLIC_KEY:YOUR_SECRET_KEY" \
  -d '{
    "batch": [{
      "id": "event-1",
      "type": "trace-create",
      "timestamp": "2026-01-01T00:00:00.000Z",
      "body": {
        "id": "my-first-trace",
        "name": "my-first-trace",
        "input": "Hello",
        "output": "Hello back"
      }
    }]
  }'

Ingestion is asynchronous: the web tier writes the raw event to the events/ prefix of your bucket, the worker takes it off the Redis queue and writes it into ClickHouse, and the trace appears in the UI a few seconds later.

For the playground and LLM-as-a-judge evaluations, add provider API keys under Settings → LLM Connections. They are stored encrypted with your encryptionKey.

Operations

Backing Up

PostgreSQL is the one datastore that must be backed up: it holds users, projects, API keys, prompts, datasets and evaluation configs. ClickHouse keeps its data parts in your bucket and is as durable as that bucket — its volume set holds local metadata only. Redis holds only the transient ingestion queue and cache. Two paths cover PostgreSQL. A volume set snapshot captures the full disk state:

cpln volumeset snapshot create RELEASE_NAME-pg-vs --gvc GVC_NAME --snapshot-name NAME
cpln volumeset snapshot get RELEASE_NAME-pg-vs --gvc GVC_NAME

Or enable the bundled postgres template’s scheduled dump, which adds the RELEASE_NAME-postgres-backup cron workload and uploads a gzipped pg_dumpall to a bucket of your choice. It is off by default:

postgres:
  backup:
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 # tag 18.1.0 = Postgres 18, 17.1.0 = Postgres 17
    schedule: "0 2 * * *"   # daily at 2am UTC
    provider: aws # Options: aws, gcp, or minio
    aws:
      bucket: my-postgres-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: my-postgres-backup-policy # bucket-scoped IAM policy
      prefix: postgres/backups # folder name where your backups will be stored

The bundled database’s identity picks up the bucket-scoped policy automatically. For the bucket, cloud account and IAM policy setup per provider — including the gcp and minio blocks — follow the postgres template’s backup prerequisites; the keys there live under postgres.backup.* here.

A zero-length backup object is a failed run, not a backup. If the dump cannot reach the database, the upload still writes a tiny empty gzip under a normal timestamped filename. Check the object size before relying on one.

Restoring a Backup

These paths have not been exercised against this template; verify them on a throwaway release before relying on them.

From a scheduled dump: the dump is a plain pg_dumpall output restored with psql against RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432, using the username and password from your database credentials secret. The command sequence per provider is on the postgres template’s restore section; it must run from a client that can reach the bucket and the database, which means a workload inside the GVC.
From a volume set snapshot: cpln volumeset snapshot restore exists (check cpln volumeset snapshot restore --help) but has not been run against this template.
ClickHouse: trace data is in your bucket under clickhouse/. A fresh ClickHouse workload pointed at the same bucket is the recovery path, but it has not been verified; deleting the bucket loses all trace history regardless of snapshots.

Upgrading from 1.0.0 or 1.0.1

Version 1.1.0 removed six values keys and moved all auth key material into the prerequisite auth secret. A values file that still carries any of them fails at render, so the upgrade aborts before anything is applied and the live release is untouched — but it does not proceed until the keys are gone. There are no compatibility fallbacks.

Removed in 1.1.0	Replacement
`langfuse.auth.nextAuthSecret`	`nextAuthSecret` key in the secret named by `langfuse.auth.secretName`
`langfuse.auth.encryptionKey`	`encryptionKey` key in the same secret
`langfuse.auth.salt`	`salt` key in the same secret
`objectStore.gcp.accessKeyId`	`accessKeyId` key in the secret named by `objectStore.gcp.credentialsSecretName`
`objectStore.gcp.secretAccessKey`	`secretAccessKey` key in the same secret
`langfuse.firewall.inboundAllowCIDR`	`publicAccess.enabled` and `internalAccess.type`

Each one fails with a message naming its replacement, for example:

langfuse.auth.nextAuthSecret was removed in 1.1.0. Put it in the prerequisite dictionary secret
named by langfuse.auth.secretName (key: nextAuthSecret) — see the README.

Back up PostgreSQL

Take a volume set snapshot of RELEASE_NAME-pg-vs before changing anything (see Backing Up).

Create the prerequisite secrets

Create the auth secret with all five keys, and on the GCS path the credentials secret as well (see Prerequisites). adminEmail and adminPassword have no 1.0.x equivalent — they provision the owner account.

Remove the six keys and name the secrets

Delete every removed key from your values, set langfuse.auth.secretName and, on GCS, objectStore.gcp.credentialsSecretName. Replace langfuse.firewall.inboundAllowCIDR with publicAccess.enabled and internalAccess.type.

Upgrade and verify

Run the upgrade, then confirm RELEASE_NAME-langfuse-web and RELEASE_NAME-langfuse-worker reach ready with cpln workload get-deployments RELEASE_NAME-langfuse-web --gvc GVC_NAME -o yaml.

Treat the 1.0.x auth defaults as compromised. Versions 1.0.0 and 1.0.1 shipped working values for nextAuthSecret, encryptionKey and salt as defaults in a public repository, so any install that did not override them shared one publicly known set. Generate fresh values for all three. The trade-off on encryptionKey: carrying the old one forward keeps existing LLM connections readable but leaves them encrypted under a published key; a new one makes them undecryptable and they must be re-added under Settings → LLM Connections.

Upgrading from 1.1.0

postgres.config.username, .password and .database were removed. Put the values your database was initialized with into a database credentials secret as under Prerequisites (keys username, password, database), under any name except RELEASE_NAME-pg-config (the secret 1.1.0 created, which this upgrade deletes). Set postgres.config.credentialsSecretName to it and remove the three keys. The Redis and ClickHouse passwords move to prerequisite secrets too: follow Upgrading from 1.2.x for them (1.1.0 keeps them in the same RELEASE_NAME-langfuse-config secret). The auth path is unchanged.

Upgrading from 1.2.0

Version 1.2.1 removes the AWS managed policy aws::ReadOnlyAccess from the identity this template links to your AWS cloud account. That policy granted read access to every bucket in your AWS account and contained no write actions, so it was never carrying the object store itself — but it was silently supplying any read action your bucket-scoped policy omitted. The identity now carries cpln-connector and your own policy only. Before upgrading, update your IAM policy to the ten-action list in Prerequisites — 1.2.0 documented six actions. If it already matches, no action is needed. Nothing else changes.

Upgrading from 1.2.x

Version 1.3.0 removed postgres.credentials, redis.auth.password and clickhouse.config.password: all three datastores now read prerequisite secrets, and carrying any old key forward fails the render. 1.2.x created the database secret itself, so this upgrade deletes it. Before upgrading, create a secret under a new name holding the values your database was initialized with — not new ones, or Langfuse loses its database connection:

cpln secret create-dictionary --name RELEASE_NAME-langfuse-db \
  --entry username='YOUR_CURRENT_USERNAME' --entry password='YOUR_CURRENT_PASSWORD' --entry database='YOUR_CURRENT_DATABASE'

Your current values are in postgres.credentials of the 1.2.x release, and also in the old secret named by postgres.config.credentialsSecretName in 1.2.x (cpln secret reveal SECRET_NAME -o yaml) until the upgrade deletes it. 1.2.x kept the Redis and ClickHouse passwords in RELEASE_NAME-langfuse-config (keys redisPassword, clickhousePassword), which this upgrade also deletes, so use other names. Create them holding your current passwords, so the old and new versions keep talking to each other during the rollout:

cpln secret create-dictionary --name RELEASE_NAME-langfuse-redis-credentials \
  --entry password='YOUR_CURRENT_REDIS_PASSWORD'

cpln secret create-dictionary --name RELEASE_NAME-langfuse-clickhouse-credentials \
  --entry username=default --entry password='YOUR_CURRENT_CLICKHOUSE_PASSWORD'

Your current values are redis.auth.password and clickhouse.config.password of the 1.2.x release, and also in cpln secret reveal RELEASE_NAME-langfuse-config -o yaml until the upgrade deletes it. Then upgrade with postgres.config.credentialsSecretName, redis.credentialsSecretName and clickhouse.credentialsSecretName set to those names, and postgres.credentials, redis.auth and clickhouse.config.password removed. The upgrade restarts the bundled PostgreSQL (it now reads the new secret), so Langfuse briefly loses its database and reconnects by itself. While access to the new secrets propagates, the new version of a workload can wait in get-deployments reporting that it is not allowed to reveal the secret; the previous version keeps serving meanwhile, and it clears by itself.

Upgrading from 1.3.0

Version 2.0.0 moves Langfuse 3 to Langfuse 4, and ClickHouse 25.10 to 26.8 (Langfuse 4 needs 25.12 or newer). It is an in-place helm upgrade of the existing release: the data stays where it is, the web and worker workloads wait until ClickHouse reports the new version, and the web workload then applies the Langfuse 4 database migrations at start. The upgrade is one-way. After the migrations, a 1.3.0 web container exits at start, and moving ClickHouse back to 25.10 on the same data is not supported. Going back means restoring PostgreSQL from a backup; this template has no ClickHouse backup. Langfuse documents a manual schema rewind for the time before the cutover. Before you upgrade:

A release older than 1.3.0 goes to 1.3.0 first, following the matching sections above.
Check that every Langfuse 3 background migration has finished, because Langfuse 4 drops the tables they copy from. The five 20260701_v4_step_* migrations are already listed on 1.3.0 but run only on Langfuse 4, so the query leaves them out. It must print no rows:
cpln workload exec RELEASE_NAME-postgres --gvc GVC_NAME --container postgresql -- \ sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT name, failed_reason FROM background_migrations WHERE finished_at IS NULL AND name NOT LIKE '"'"'20260701_v4_step_%'"'"';"'
If it prints rows, check the UI (Langfuse version tag, then Background Migrations). The worker runs background migrations only when it starts, and gives up if PostgreSQL is not reachable yet, so rows that never started are run by restarting it:
cpln workload force-redeployment RELEASE_NAME-langfuse-worker --gvc GVC_NAME
Back up PostgreSQL (see Backing Up) and check the backup object is not empty.
Choose the write mode. It decides what keeps working from Langfuse 3:

`langfuse.migration.writeMode`	Choose it when
`events_only` (default)	No producer runs Python SDK v2 or JS/TS SDK v3 or older (rejected); Python SDK 4.7+, JS/TS SDK 5.4+ or plain OpenTelemetry write directly (Python 4.0-4.6 and JS/TS 5.0-5.3 ingest with a delay); nothing uses the legacy APIs or trace-level evaluators. Writes only the new tables.
`dual`	Some producers still run older SDKs, or you want the old tables kept as a safety net. Writes the old and the new tables; data from older SDKs shows up after about 15 minutes.
`legacy`	You want Langfuse 4 with Langfuse 3 behaviour for now. Writes only the old tables. Set `historicBackfill: false`.

With events_only, the following stop working: Python SDK v2 and older and JS/TS SDK v3 and older (rejected at ingestion), the legacy read endpoints such as GET /api/public/traces and GET /api/public/observations (404), every POST /api/public/ingestion event except scores, trace-level LLM-as-a-judge evaluators, and the “Traces and observations (legacy)” export source. historicBackfill: true copies the traces stored before the upgrade into the new tables, once, in the worker, newest first: older traces appear gradually, and the progress is under Background Migrations. While it runs the bucket holds up to about three times the current ClickHouse data. A scratch copy of the old observations stays in the bucket afterwards: the last step, which drops it, is off by default upstream, so Background Migrations keeps showing one unfinished row. After a backfill on top of dual, a trace can appear twice in the UI until ClickHouse merges the two copies in the background; the data is not damaged. With dual, Langfuse suggests leaving it off until the dual write is confirmed working, then turning it on in a later helm upgrade. With legacy it must be off. When every producer and consumer has moved, cut over with a helm upgrade setting writeMode: events_only (and historicBackfill: true if it has not run). From then on new data lands only in the new tables, so this is the point of no return. The traces list is now an Observations view filtered to Is Root Observation = true, one row per trace; clear the filter to see every observation.

Rotating Credentials

A running workload keeps the credential values it started with, so every rotation ends with a forced redeployment. Change one key and keep the others with export, edit, apply:

cpln secret reveal SECRET_NAME -o yaml > secret.yaml
# edit only the key you are rotating in secret.yaml
cpln apply -f secret.yaml
cpln secret reveal SECRET_NAME -o yaml

Database password: PostgreSQL reads the secret only when it is first initialized, so run ALTER ROLE in the database first, then update the secret, then right away force a redeployment of RELEASE_NAME-langfuse-web and RELEASE_NAME-langfuse-worker. Do not redeploy the database; it would only add downtime. Connections already open keep working after ALTER ROLE, new ones fail until the redeploy finishes, so rotate in a quiet window.
Redis and ClickHouse passwords: neither datastore keeps its password in its data (Redis takes it on the command line, ClickHouse defines its user from the secret at every start), so there is no ALTER step. Update the secret, then force a redeployment of the datastore and of everything that connects to it, together:

cpln workload force-redeployment RELEASE_NAME-langfuse-redis --gvc GVC_NAME   # or RELEASE_NAME-langfuse-clickhouse
cpln workload force-redeployment RELEASE_NAME-langfuse-web --gvc GVC_NAME
cpln workload force-redeployment RELEASE_NAME-langfuse-worker --gvc GVC_NAME

Between the datastore restarting and the Langfuse workloads coming back, Langfuse cannot reach that datastore, so rotate in a quiet window. Changing the ClickHouse username works the same way.

Scaling and Availability

The web tier autoscales on CPU between langfuse.web.minReplicas and langfuse.web.maxReplicas. Keep the minimum at 2 or more for rolling deploys without downtime.
The worker runs a fixed langfuse.worker.replicas; raise it for higher ingestion throughput.
PostgreSQL, Redis and ClickHouse are single-instance on persistent volume sets. A node failure reschedules each and reattaches its volume, so the cost is minutes of downtime, not data loss.
The first helm upgrade after an install can restart the bundled datastores even when nothing changed; plan it as a short ingestion interruption and check that traces land again afterwards rather than trusting the health endpoint, which stays green throughout.
Settings carried in the web container’s environment — langfuse.auth.disableSignup, langfuse.publicUrl, any change to the auth secret — take effect only as the web replicas roll. Changing a value in the auth secret does not redeploy anything by itself; run cpln workload force-redeployment RELEASE_NAME-langfuse-web --gvc GVC_NAME and the same for RELEASE_NAME-langfuse-worker.

Troubleshooting

Web and worker never become ready and cpln logs returns nothing

Symptom: cpln helm install succeeded, but RELEASE_NAME-langfuse-web and RELEASE_NAME-langfuse-worker stay not-ready with no container output. status.versions[].message reads

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Cause: a secret named by langfuse.auth.secretName, postgres.config.credentialsSecretName, redis.credentialsSecretName, clickhouse.credentialsSecretName (or, on GCS, objectStore.gcp.credentialsSecretName) did not exist at install time. Check the datastore workloads the same way.Fix: create it as shown in Prerequisites. The deployment recovers on its own after a few minutes, or force it:

cpln workload get-deployments RELEASE_NAME-langfuse-web --gvc GVC_NAME -o yaml
cpln workload force-redeployment RELEASE_NAME-langfuse-web --gvc GVC_NAME

Render fails with a key was removed in 1.3.0

Symptom: helm upgrade aborts with postgres.credentials was removed in 1.3.0 ... (or the same for redis.auth.password or clickhouse.config.password).Cause: your values file still carries a 1.2.x datastore credential key.Fix: follow Upgrading from 1.2.x.

Render fails with a key was removed in 1.1.0

Symptom: helm upgrade aborts with langfuse.auth.nextAuthSecret was removed in 1.1.0 ... (or the same for encryptionKey, salt, objectStore.gcp.accessKeyId, objectStore.gcp.secretAccessKey, langfuse.firewall.inboundAllowCIDR).Cause: your values file still carries a 1.0.x key.Fix: follow Upgrading from 1.0.0 or 1.0.1.

Render fails with publicUrl must include the scheme

Symptom: langfuse.publicUrl must include the scheme, e.g. https://langfuse.example.com.Cause: langfuse.publicUrl was set to a bare hostname.Fix: prefix it with https:// (or http://).

Symptom: the sign-up form reports registration as disabled, and POST /api/auth/signup returns HTTP 422 with {"message":"Sign up is disabled."}.Cause: langfuse.auth.disableSignup is true, the default. This is the intended closed instance.Fix: sign in with the adminEmail / adminPassword from your auth secret and invite users from inside Langfuse, or set langfuse.auth.disableSignup: false and upgrade if you want self-service registration.

Changed adminPassword in the secret but the old password still works

Symptom: you updated adminPassword (or adminEmail) in the auth secret and redeployed, but the login did not change.Cause: headless initialization only creates the owner account when it does not exist yet; it does not update an existing user.Fix: change the password from inside Langfuse under the user’s settings. The values in the secret matter only for a fresh database.

Database connection errors in web and worker logs on a cold install

Symptom: the first log lines of RELEASE_NAME-langfuse-web and RELEASE_NAME-langfuse-worker show Can't reach database server or Applying database migrations failed while RELEASE_NAME-postgres is still starting.Cause: startup ordering. The web and worker tiers retry and apply migrations once PostgreSQL accepts connections.Fix: none needed if the workloads reach ready. If they keep failing, check RELEASE_NAME-postgres with cpln workload get-deployments RELEASE_NAME-postgres --gvc GVC_NAME -o yaml and its logs:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-postgres"}' --limit 50 --since 10m

ClickHouse starts on GCS but object storage operations fail with an auth error

Symptom: RELEASE_NAME-langfuse-clickhouse becomes ready, but writes to the bucket fail with an access or signature error in its logs.Cause: on the gcp path ClickHouse reads the HMAC pair from the accessKeyId and secretAccessKey keys of the secret named by objectStore.gcp.credentialsSecretName. A wrong key name, a key for a different service account, or a service account without roles/storage.objectAdmin all surface here.Fix: check the secret’s keys with cpln secret reveal GCS_CREDENTIALS_SECRET_NAME -o yaml, confirm the HMAC key belongs to the service account that was granted access, then force a redeployment:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-langfuse-clickhouse"} |= "ERROR"' --limit 50 --since 10m
cpln workload force-redeployment RELEASE_NAME-langfuse-clickhouse --gvc GVC_NAME

Important Notes

Create the auth, database, Redis and ClickHouse credentials secrets before installing; a missing one leaves the workloads waiting on a secret that does not exist, named only in status.versions[].message of cpln workload get-deployments RELEASE_NAME-langfuse-web --gvc GVC_NAME -o yaml.
Rotating any of these secrets needs a forced redeployment; the database password also needs ALTER ROLE first (see Rotating Credentials).
encryptionKey can never be rotated: it encrypts every provider key stored under Settings → LLM Connections, and changing it makes all of them unreadable. Keep a copy outside Control Plane and never delete the secret.
Sign-up is closed by default and the owner account comes from your secret. Record adminPassword — it is displayed nowhere, and with sign-up closed there is no other way to create the first account.
Give each install its own bucket. Two installs on one bucket share ClickHouse data parts under clickhouse/.
Give each release its own database, Redis and ClickHouse secrets. Secret names are org-wide, so two releases pointed at one secret share a password, and rotating it for one breaks the other.
Upgrading from 1.3.0 is one-way and changes what older SDKs and the legacy APIs can do: read Upgrading from 1.3.0 before you upgrade.
Serving Langfuse on your own domain requires langfuse.publicUrl, including the scheme.
With publicAccess.enabled: false there is no browser path to the UI; only other workloads in the GVC can reach the API.
Prerequisite secrets are not owned by the release: the auth, datastore credentials and GCS credentials secrets survive helm uninstall and must be deleted by hand if no longer wanted.
Uninstall deletes the volume sets, including PostgreSQL’s. Trace data already in your bucket is untouched, but users, projects and API keys are not — back up PostgreSQL first.

External References

Langfuse Documentation

Full Langfuse product documentation

Langfuse SDKs

Python, TypeScript, and other language SDK guides

Self-Hosting Guide

Self-hosting architecture and operations

Configuration Reference

Every Langfuse environment variable and what it controls

Headless Initialization

How the bootstrapped owner account is provisioned

Template Catalog

Templates

Langfuse

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Object Store

Langfuse

Access

PostgreSQL

Redis

ClickHouse

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.0 or 1.0.1

Upgrading from 1.1.0

Upgrading from 1.2.0

Upgrading from 1.2.x

Upgrading from 1.3.0

Rotating Credentials

Scaling and Availability

Troubleshooting

Important Notes

External References

Langfuse Documentation

Langfuse SDKs

Self-Hosting Guide

Configuration Reference

Headless Initialization

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Object Store

​Langfuse

​Access

​PostgreSQL

​Redis

​ClickHouse

​Connecting

​First Run

​Operations

​Backing Up

​Restoring a Backup

​Upgrading from 1.0.0 or 1.0.1

​Upgrading from 1.1.0

​Upgrading from 1.2.0

​Upgrading from 1.2.x

​Upgrading from 1.3.0

​Rotating Credentials

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Langfuse Documentation

Langfuse SDKs

Self-Hosting Guide

Configuration Reference

Headless Initialization

Overview

What Gets Created

Prerequisites

Installation

Configuration

Object Store

Langfuse

Access

PostgreSQL

Redis

ClickHouse

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.0 or 1.0.1

Upgrading from 1.1.0

Upgrading from 1.2.0

Upgrading from 1.2.x

Upgrading from 1.3.0

Rotating Credentials

Scaling and Availability

Troubleshooting

Important Notes

External References