Deploy and Operate Langfuse
Langfuse traces LLM calls, manages prompts, runs evaluations, and stores datasets. Edka deploys it as a managed app in your Kubernetes cluster and points it at datastores that already run there.
This integration uses Edka’s Langfuse chart. It installs the web and worker Deployments only, and does not add another PostgreSQL, ClickHouse, or Valkey next to them. You select an existing installation of each, plus an organization object storage integration, and Edka projects their credentials into one runtime Secret.
Architecture
Section titled “Architecture”| Component | Purpose | How Edka connects it |
|---|---|---|
| Langfuse web | UI, API, and trace ingestion endpoint on port 3000 | Installed from the Edka Langfuse chart as <release>-web |
| Langfuse worker | Background processing of queued events | Same chart release, deployed as <release>-worker |
| PostgreSQL | Projects, users, prompts, and API keys | Select an installation, database, and user from the Databases workspace |
| ClickHouse | Traces and events | Select an installation and name a dedicated database |
| Valkey | Queues and cache between web and worker | Select an existing Valkey installation |
| Object storage | Event uploads, batch exports, and media | Select an S3-compatible object storage integration |
| Traffic class | Optional external HTTPS access | Select a traffic class and hostname |
Prerequisites
Section titled “Prerequisites”Before installing Langfuse, prepare:
- a managed PostgreSQL installation with a database and a login user for Langfuse
- a managed ClickHouse installation, with a dedicated database created for Langfuse
- a managed Valkey installation
- an Amazon S3 or S3-compatible object storage integration; Azure Blob Storage and Google Cloud Storage are not accepted
- a traffic class and a DNS hostname, if you want Langfuse reachable from outside the cluster
All three datastores must be in the ready state to appear in the Langfuse
form. Create them in the Databases workspace and
add the storage target under
Object Storage Integrations first.
Install Langfuse
Section titled “Install Langfuse”- Open your cluster and select Apps.
- Find Langfuse and select Install.
- In General, choose the Namespace (default
langfuse), review Langfuse Chart Version and Langfuse Image Tag, and decide whether to enable Auto-update App. - In Datastores, select the PostgreSQL Installation, PostgreSQL Database, and PostgreSQL User, then the ClickHouse Installation, the ClickHouse Database name, and the Valkey Installation.
- In Object Storage, select the Object Storage integration for events, exports, and media.
- In Security, keep the generated Salt, Session Secret, and Encryption Key, add an Enterprise License Key if you have one, and set the signup and authentication switches.
- In Resources, review Node.js Options, replicas, and the request and limit values.
- In Access, enable Expose Langfuse if you want an external hostname.
- Select Install App and follow the operation progress until Langfuse is ready.
Namespace, Salt, Session Secret, and Encryption Key are locked once the app is installed. Everything else stays editable.
Datastore Connections
Section titled “Datastore Connections”Edka resolves connection details from the selected installations, so the hosts, ports, and credential Secrets are filled in for you.
PostgreSQL
Section titled “PostgreSQL”Edka connects to <runtime-name>-rw.<namespace>.svc.cluster.local on port
5432 and reads the selected user’s password from the Kubernetes Secret that
the installation maintains for that user.
The PostgreSQL Database and PostgreSQL User lists are filtered to the selected installation. Both must be objects that installation manages, so create the database and the login role in the Databases workspace before installing Langfuse.
ClickHouse
Section titled “ClickHouse”Edka fills the host, protocol, HTTP port 8123, and native port 9000 from
the selected installation, and connects as the ClickHouse default user using
that installation’s password Secret. The protocol is https when the
installation requires TLS and http otherwise.
ClickHouse Database is a free text field with the default langfuse. The
database has to exist on the selected installation before Langfuse starts. The
Databases workspace manages users and databases for PostgreSQL and MySQL only,
so create the ClickHouse database with a ClickHouse client.
Give Langfuse its own ClickHouse database rather than pointing it at default.
Langfuse owns its schema_migrations table and will conflict with anything
else that keeps migration state in the same database.
Valkey
Section titled “Valkey”Edka fills the host, port 6379, database index 0, and user default. When
the installation has authentication enabled, Edka reads its auth Secret and
writes the password into the Langfuse runtime Secret under redis-password.
Object storage
Section titled “Object storage”Edka copies the bucket, region, endpoint, path-style setting, and the access key pair from the selected integration into the runtime Secret. Amazon S3 integrations resolve to virtual-hosted addressing with no custom endpoint. S3-compatible integrations keep their own endpoint and Force Path Style setting:
- enabled:
https://endpoint/bucket/key, common for MinIO and similar endpoints without bucket subdomains - disabled:
https://bucket.endpoint/key, common for AWS-style providers
When the integration has no region, Edka sends auto.
Runtime Secrets
Section titled “Runtime Secrets”All Langfuse credentials live in one Secret named <release>-runtime in the
app namespace. Edka creates it and points the chart at it, so the chart does
not manage its own Secret.
| Secret | Purpose | Handling |
|---|---|---|
| Salt | Stable Langfuse hashing salt | Generated at install, 32 characters, minimum 16, locked afterwards |
| Session Secret | NextAuth session secret | Generated at install, 48 characters, minimum 32, locked afterwards |
| Encryption Key | Langfuse encryption key | Generated at install, 64 hexadecimal characters, locked afterwards |
| Enterprise License Key | Optional Langfuse Enterprise license | Supplied by you; leaving the field empty during an update keeps the stored key |
| PostgreSQL password | Database login for the selected user | Read from the selected user’s password Secret on every apply |
| ClickHouse password | Login for the ClickHouse default user | Read from the installation’s default user Secret on every apply |
| Valkey password | Queue and cache authentication | Read from the installation’s auth Secret when authentication is enabled |
| Object storage keys | S3 access key ID and secret access key | Copied from the selected object storage integration |
The three generated values are locked after installation because Langfuse data
depends on them staying the same. If you plan to uninstall and later reinstall
against the same PostgreSQL, ClickHouse, and bucket data, copy the
<release>-runtime Secret out of the cluster first.
Configuration updates preserve every value above. Edka reads the existing Secret, carries the current values forward, and regenerates nothing that is already set.
Authentication and Telemetry
Section titled “Authentication and Telemetry”The Security tab controls sign-in behavior. All three switches are off by default.
- Disable Signups closes username and password signup. Enable it after the initial organization and its users exist.
- Disable Password Auth turns off Langfuse username and password authentication entirely. The Edka form configures no other sign-in provider, so enabling it leaves no sign-in method configured through Edka.
- Langfuse Telemetry allows Langfuse product telemetry from this deployment.
Resources and Scaling
Section titled “Resources and Scaling”| Deployment | Replicas | CPU request | Memory request | CPU limit | Memory limit |
|---|---|---|---|---|---|
| Web | 1 | 250m | 1Gi | 1000m | 2Gi |
| Worker | 1 | 250m | 1Gi | 1000m | 2Gi |
Those are the defaults from the Resources tab.
Web and worker scale independently. Raise Worker Replicas when queued
events lag behind ingestion, and Web Replicas when the UI or API is slow.
Both accept 1 to 10.
Node.js Options defaults to --max-old-space-size=1536 and applies to both
processes. Raise it together with the memory limits when you give the pods more
memory, and keep it below the limit so the heap stays inside the container.
Langfuse itself keeps no persistent volume. All state lives in PostgreSQL, ClickHouse, Valkey, and the bucket.
Access and Endpoints
Section titled “Access and Endpoints”Exposure is optional. With Expose Langfuse off, Langfuse is reachable only inside the cluster and its public URL is the internal service address.
Enable Expose Langfuse to publish the web UI and API, then select a
Traffic Class and enter a Hostname such as langfuse.example.com. When
the traffic class is an Envoy Gateway class, Edka attaches an HTTPRoute for
that hostname to the Gateway. Other classes get an Ingress with the selected
class name. See Gateway API and
Domains and TLS.
After installation, Edka shows:
- the internal service endpoint
http://<release>-web.<namespace>.svc.cluster.local:3000 - the external URL
https://<hostname>when exposure is enabled
The hostname also sets Langfuse’s own public URL, which it uses when building absolute links.
Hermes Agent Tracing
Section titled “Hermes Agent Tracing”A Hermes Agent in the same cluster can send traces to an installed Langfuse instance. In the Hermes Agent configuration, open the Observability tab:
- Enable Langfuse Tracing.
- Select the Langfuse Instance. Edka fills Langfuse Base URL with that
instance’s in-cluster address,
http://<release>-web.<namespace>.svc.cluster.local:3000, so traffic stays inside the cluster. - Create a project in Langfuse and paste its Langfuse Public Key
(
pk-lf-...) and Langfuse Secret Key (sk-lf-...). - Set Langfuse Environment, the label attached to traces. The default is
production.
The instance picker lists the Langfuse apps installed in the cluster with their
current status, so install Langfuse before enabling tracing. Edka stores the
secret key in the Hermes Agent config Secret and allows egress from the Hermes
pod to pods labeled app.kubernetes.io/name: langfuse on TCP port 3000.
You can also point any application at Langfuse using the internal service endpoint and a project key pair. See Agents for the Hermes runtime itself.
Updates
Section titled “Updates”Auto-updates are opt-in and cover two targets: the Edka Langfuse chart from
https://charts.edka.io, and the langfuse/langfuse image tag applied to both
the web and worker Deployments.
Enable Auto-update App, then choose:
- Auto-update Policy: patch, minor, major, all, or custom. The default is minor.
- Custom Tag Pattern, shown for the custom policy: a tag filter using a
glob:orregexp:prefix. - Auto-update Check: every 5 minutes, 30 minutes, hour, 6 hours, or daily. The default is every 30 minutes.
With auto-updates off, change Langfuse Chart Version and Langfuse Image Tag manually. Updates preserve the runtime Secret, so sessions and encrypted data survive the upgrade.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| An installation is missing from a datastore picker | Only databases in the ready state are selectable |
| Selected managed PostgreSQL database is unavailable | Pick a database the selected installation manages, or create it in the Databases workspace |
| Selected managed PostgreSQL user is unavailable | Pick a login role the selected installation manages |
| Langfuse requires an S3-compatible object storage integration | Select an Amazon S3 or S3-compatible integration; Azure Blob Storage and Google Cloud Storage are not accepted |
| Value must be hexadecimal | The Encryption Key must be 64 hexadecimal characters; use the generate action |
| Invalid domain name | Enter a bare hostname such as langfuse.example.com, without a scheme or path |
| Web or worker pod stays unready | Verify PostgreSQL, ClickHouse, Valkey, and object storage reachability and credentials, then review Logs |
| ClickHouse migration errors | Give Langfuse a dedicated ClickHouse database; it owns its schema_migrations table |
| Ingestion lags behind incoming traces | Raise Worker Replicas, up to 10 |
| A pod is OOMKilled | Raise the memory limit and --max-old-space-size in Node.js Options together |
| Langfuse secret key is required when Hermes Langfuse tracing is enabled | Enter the project secret key in the Hermes Agent Observability tab |