Overview
Upgrade and support work for self-hosted Langfuse keeps your tracing stack current and compatible with the SDKs your applications run. It covers three kinds of change. Updates within a major version are non-disruptive, and Langfuse applies database migrations automatically when the Langfuse Web and Langfuse Worker containers start. Major upgrades, such as v2 to v3 or v3 to v4, follow dedicated migration guides and need planning. Between those two sits the supporting layer: the Helm chart, the PostgreSQL, ClickHouse and Redis or Valkey versions, and the S3-compatible blob storage that the application depends on.
Upgrades are triggered by a new release, a security fix, a data store version that falls outside what the current Langfuse release requires, or a planned move to a new major version. The v3 to v4 guide, for example, requires ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later. Before any change, confirm the versions running in your environment against the current release notes and the upgrade guide, and check whether your Helm chart still uses bundled data stores that need their own upgrade step.
SDK compatibility is part of the same decision. The Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later, so a server upgrade can affect application teams who have not yet moved their SDKs. Inventory which SDK versions each service uses before you schedule the server change.
Keep the upgrade in-house when your platform team already runs Kubernetes and PostgreSQL, the version gaps are small, and someone can read a migration guide and test it in a non-production environment. Bring in a partner when a major move involves a data model change, when several data stores are out of range at once, or when you need documented change control and evidence for an assessment. The support scope, including whether the Enterprise support SLA applies, should be confirmed in writing before the work starts.
What the work includes
Each upgrade is planned, rehearsed and verified as a set of work packages, with the same deliverables handed over at the end.
Current-state assessment and baseline
Record the running Langfuse version, the PostgreSQL, ClickHouse and Redis or Valkey versions, and the blob storage configuration. If you deployed the Helm chart with bundled data stores, confirm the chart version too, because Langfuse requires the chart to move from v1 to v2 before Langfuse moves to v4. Capture the current configuration as a versioned baseline.
Target version selection
Choose the target from the Langfuse releases list and check it against the v3 to v4 guide, which requires ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later. Confirm that the SDK versions you plan to keep are supported by the target. Record why the chosen release fits and what is deferred.
Runbook and staging rehearsal
Write step-by-step commands, expected output, checkpoints and an owner for each stage. Rehearse in staging with a restored copy of production data, confirm the backup restore actually works, and log every deviation. Rehearsal findings drive the production plan, including the ClickHouse disk headroom needed for any historic data backfill.
Production change window and rollback path
Agree the change window, approvers and go or no-go criteria before the day. Take fresh backups of PostgreSQL, ClickHouse and blob storage, then define the rollback trigger and the restore steps for each store. Because a rollback after data migration depends on restored backups, the reversal path should be tested in staging before the window opens.
Post-upgrade verification and SDK compatibility
Check that Web and Worker containers are healthy, migrations completed, the UI and APIs respond, and new traces and scores are arriving. Run the SDK compatibility check against your applications, since Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later. Keep the test evidence, including sample trace IDs, with the release record.
Handover and post-go-live support
Hand over the runbook, version and compatibility matrix, test evidence, rollback plan and updated configuration, and walk your operators through them. Post-go-live support is a separate option agreed in writing. Langfuse's Self-Hosted Enterprise plan adds a named support engineer and a support SLA, so confirm which party covers which tier.
What drives effort and duration
Each driver shows why it changes the upgrade effort and what the client can do before work starts to keep it under control.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Distance between current and target version | Updates within a major version apply migrations at startup. Moving to v4 changes the ClickHouse data model and adds a backfill. | Stay on current releases within your major version so the v4 step is the only major change. |
| Bundled versus external data stores | Helm users with bundled data stores must move to chart v2 before Langfuse v4. External stores add version checks and connectivity work. | Record each data store version now and confirm it meets the v4 minimums in the upgrade guide. |
| Number of environments | Each environment repeats the upgrade and needs its own rehearsal before production. | Keep Helm values and infrastructure code identical across development, staging and production. |
| Helm chart version | Chart major versions can change values keys and how bundled data stores are handled, so old values files often need rewriting. | Keep the chart current and compare your values file with the chart defaults before each change. |
| Instrumented applications and SDK versions | Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later. Applications on unpinned SDKs can break at upgrade time. | Pin SDK versions in each application, assign an owner per application and check traces after each step. |
| Data volume and backfill | The v4 guide advises about 3x ClickHouse disk headroom for backfilling historic data, so volume sets disk needs and rehearsal time. | Measure current ClickHouse disk use, confirm retention settings and rehearse the backfill on a production-sized copy. |
| Enterprise license features configured | Features such as project RBAC, protected prompt labels, audit logs and SCIM need a license key and add settings to test after upgrade. | List every enabled enterprise feature in the configuration record and test each one in staging. |
| Kubernetes or Docker Compose platform | Langfuse documents Docker Compose on one VM for testing only, without high availability. Production runs on Kubernetes with Helm or Terraform. | Run production on Kubernetes and confirm your cluster version and tooling are supported before planning the upgrade. |
Project phases and outputs
The sequence moves a self-hosted Langfuse deployment from a known inventory to a verified target version, with a tested rollback path and a documented support scope at handover.
Inventory versions and dependencies
The partner records the running Langfuse version, deployment method (Docker Compose or Kubernetes with Helm or Terraform), PostgreSQL, ClickHouse, Redis or Valkey and blob storage versions, SDK versions in each application, and whether the Helm chart uses bundled data stores. The output is a dependency inventory with each component's current version and the gaps that block the upgrade path. Confirm with the partner who owns each item and which versions they will check against the vendor's current requirements.
Select the target upgrade path
Using the Langfuse upgrade guide, the version-specific migration guide and the release notes for each release between current and target, the partner selects the target version and the ordered steps to reach it. For a v3 to v4 move, this covers the ClickHouse, PostgreSQL and Redis minimums, the observations-first data model change, backfill headroom and any Helm chart step. The output is a written upgrade path with prerequisites and go or no-go criteria. Ask the partner to confirm whether intermediate releases are required.
Rehearse the upgrade in staging
The partner builds a staging environment that matches production topology as closely as practical, takes a backup, and runs the full upgrade. They then restore that backup into a separate environment to prove recovery works, and record migration duration, disk growth and any errors. The output is a rehearsal log, a verified backup and restore record, and a list of changes to the runbook. Ask the partner how staging data volume compares with production and whether the rehearsal includes SDK checks.
Write the production runbook and change window
The partner turns the rehearsed steps into a production runbook with pre-checks, backup confirmation, the exact upgrade commands, post-upgrade checks, and a rollback decision point with owners named for each action. The change window is agreed with your change board and communicated to teams that send traces. The output is an approved runbook and a scheduled window. Ask the partner what triggers rollback and who holds the authority to call it.
Execute cutover and verify
The team runs the approved runbook in the change window, then verifies that web and worker containers are healthy, migrations completed, traces are arriving from instrumented applications, the UI and public API respond, and SSO sign-in works. The output is a signed verification checklist with timestamps and any deviations recorded. Ask the partner how long post-upgrade monitoring continues and which signals it watches, such as ingestion lag.
Hand over with a defined support scope
The partner delivers the as-built configuration, the updated runbook, backup and restore procedures, SDK version compatibility notes and a list of open items. The support scope is written down, stating what is covered, response expectations, upgrade assistance and what remains with your team. The output is a handover pack and a signed support scope. Confirm whether the support scope is a retainer, a fixed engagement, or the vendor's Self-Hosted Enterprise support, since these differ in what they include.
What stays in-house and what goes to a partner
This table splits Langfuse upgrade work into the parts most teams keep internally and the parts often handed to a partner, with the skills each part needs, so you can assign owners before a change window is booked.
| Work item | Usually in-house | Often outsourced to a partner |
|---|---|---|
| Change window approval | Owned by your change board and service owners, who accept the risk and timing of each upgrade | Partner prepares the change request, impact summary and rollback criteria for your board to review |
| Application SDK changes | Your application engineers update Python SDK v5 or JS/TS SDK v6 calls and confirm Langfuse v4.59.0 or later is in place | Partner identifies which SDK versions your services pin and flags compatibility gaps before the cutover |
| Business validation of traces and prompts | Product and ML owners check that scores, prompt versions and trace attributes still mean what they did before the upgrade | Partner provides a test checklist and sample queries, but does not judge whether outputs are correct for your use cases |
| Access to infrastructure | Platform team grants cluster, database and storage access and keeps privileged credentials under its own control | Partner works through agreed access paths and logs every administrative action in your change record |
| Version path planning | Architects confirm the target release and business timing, using the v3 to v4 guide as the reference | Partner maps the route from your current version, including the Helm v1 to v2 chart step where bundled data stores apply |
| Helm and data store prerequisite checks | Platform engineers confirm Kubernetes, Helm, PostgreSQL 15 or later, Redis 7.0 or later and ClickHouse 25.12 or later are in place | Partner runs the version and configuration checks, compares them with the upgrade guide and lists gaps with owners |
| Upgrade rehearsal | Your staging owners provide a copy of the environment and keep test data under your data handling rules | Partner runs the rehearsal, measures migration time and records the steps that failed or needed manual work |
| Runbook writing and cutover support | Operations staff own the on-call handover and sign off the final runbook before production | Partner drafts the runbook and stays on the cutover bridge with Kubernetes, PostgreSQL and ClickHouse administration skills |
What goes wrong and how to prevent it
Each failure below traces to a specific Langfuse upgrade requirement. Check them during planning so the change window holds.
Data store versions below minimum
Langfuse v4 requires ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later. Upgrading the application first often fails when a database or cache is older than the minimum. Prevention: inventory every data store version, including managed services, and upgrade any that fall short before the Langfuse change.
Skipping the Helm chart v1 to v2 step
Helm users with bundled data stores must move the chart from v1 to v2 before upgrading Langfuse to v4. Going straight to v4 skips a required stage in the chart's own history. Prevention: confirm which data stores your values file deploys, and run the chart step as its own change with a documented rollback point.
SDKs below the server minimum
Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later. Applications still running older SDKs may fail to send traces once the server moves forward, and the failure often appears in one service first. Prevention: inventory SDK versions across every application and upgrade them before or alongside the server change.
Production upgrade without rehearsal or backup
A major upgrade changes the schema and data model, so rollback depends on a backup that has been restored and tested. Teams that upgrade production directly find version and configuration problems during the outage. Prevention: back up PostgreSQL, ClickHouse and blob storage, restore the set into staging, run the upgrade there, and record how long each step takes before the production window.
Underestimating ClickHouse backfill headroom
The v3 to v4 guide advises about 3x ClickHouse disk headroom when backfilling historic data. Sizing disks for current usage alone can leave the backfill short of space partway through, which slows ingestion. Prevention: measure current ClickHouse disk use, apply the guide's headroom factor to the backfill, and confirm volume and alert thresholds before the upgrade begins.
Losing the Enterprise license configuration
Features such as project-level RBAC, protected prompt labels, audit logs, data retention and SCIM need an Enterprise license key on self-hosted deployments. Changes to environment variables, Helm values or secrets during an upgrade can drop the key, and the features then stop working without an obvious error. Prevention: store the key in your secrets manager, add it to the upgrade checklist, and verify each licensed feature after the change.
How the work changes by starting point
When the Helm chart deploys PostgreSQL, ClickHouse and Redis or Valkey for you, the upgrade covers both the chart and the data stores it installs. This applies to Kubernetes on AWS, Azure or GCP as well as other clusters.
- Chart sequence: Helm users with bundled data stores must upgrade the chart from v1 to v2 before upgrading Langfuse to v4. Confirm the exact order against the upgrade guide for your current chart version.
- Data store versions: Check whether the bundled images meet the v4 minimums: ClickHouse 25.12 or later, PostgreSQL 15 or later and Redis 7.0 or later. Confirm how to change image tags in your values file.
- Persistent volumes: Confirm how the chart handles existing storage claims during an upgrade, and verify a tested restore path before any change.
- Ongoing ownership: Someone on your team must patch the bundled data stores, since the chart does not replace your operational responsibility for them in production.
When PostgreSQL, ClickHouse and Redis or Valkey run outside the chart, often as managed services, the upgrade has to be coordinated with each provider's maintenance windows and version support. Langfuse itself still runs its own migrations at startup.
- Version support: Confirm that your managed PostgreSQL, ClickHouse and Redis or Valkey versions meet the v4 minimums, and check whether the provider offers those versions before you need them.
- Disk headroom: For a v4 backfill, the upgrade guide advises about 3x ClickHouse disk headroom. Confirm the provider's storage scaling options and any limits on temporary growth.
- Connection and access: Confirm connection limits, network paths and credentials for the Langfuse Web and Worker containers, and check that the migration user has the privileges it needs.
- Maintenance alignment: Schedule provider-side patching and Langfuse upgrades so that neither changes a data store while the other is mid-migration.
Langfuse documents Docker Compose on a single VM for testing only, with no high availability. Upgrades on this layout are simple but carry the full risk of a single host, so treat them as a rehearsal for production work.
- Snapshots first: Take a consistent backup or volume snapshot of PostgreSQL, ClickHouse and blob storage before pulling a new image, since a failed migration on one host has no standby.
- Compose file changes: Confirm which environment variables and service definitions changed between your current release and the target, and merge them into your file before restarting.
- Downtime: Expect the stack to restart as a whole. Confirm the expected interruption with your users before the window opens.
- Migration path: If this install will become production, plan the move to Kubernetes as a separate project and confirm that upgrades you test here will carry over to the new layout.
A deployment on v1 or v2 needs a planned sequence of major upgrades, because Langfuse publishes a dedicated migration guide for each step. Each stop changes the architecture or data model, so the path is set by the version you start from.
- Stepwise path: Confirm each required stop in the upgrade guide, from v1 to v2, v2 to v3 and v3 to v4, and decide whether an intermediate environment is needed to test each stop.
- Architecture changes: The move from v2 to v3 adds ClickHouse, so budget for a new data store and its operations, not only a version bump.
- Data model change: The v3 to v4 guide moves to an observations-first ClickHouse data model and advises about backfilling historic data. Confirm how much history you need to keep and how long the backfill will run in your environment.
- SDK alignment: Confirm which application SDKs must change alongside the server. Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later.
In an air-gapped network, the cluster cannot reach public registries, chart repositories or package indexes at upgrade time. Every release artifact has to be mirrored internally and verified before the change window.
- Container images: Mirror the Langfuse Web and Worker images and the PostgreSQL, ClickHouse and Redis or Valkey images for the exact target tags, and confirm they match the versions in the release notes.
- Chart sources: Mirror the Helm chart and any Terraform modules you use, pinned to the version you will deploy, into an internal repository.
- SDK packages: Mirror the Python and JS/TS SDK versions your applications need into your internal package index, so application teams can upgrade without public access.
- Licensing and checks: Confirm whether Enterprise license key activation requires outbound connectivity in your setup, and plan an offline validation method if it does.
What the client needs to provide
Before any upgrade plan can be written, DeployOpen needs a precise picture of what is running today. Current Langfuse version, Helm chart version and data store versions come first. Without the exact Langfuse release, the upgrade path cannot be chosen, because minor updates apply migrations automatically at startup while major jumps follow separate guides. The Helm chart version matters too: if bundled data stores are in use, the chart must move from v1 to v2 before Langfuse moves to v4. Confirm the PostgreSQL and ClickHouse versions, and Redis or Valkey where deployed, against the requirements in the relevant upgrade guide.
Next, provide the deployment manifests or Helm values files for every environment, along with the storage class, ingress and secret references they use. Those files show how web, worker and data stores were actually configured, including any split of ingestion and UI traffic. Without them, the plan rests on assumptions, and drift between staging and production will surface during the upgrade rather than before it.
Access to staging and production clusters is required for rehearsal and rollout. Staging should mirror production closely enough to test a migration, including the backfill that a v3 to v4 move performs and the extra ClickHouse disk headroom it advises. The client should also name who holds cluster credentials and who can approve a rollback.
Provide recent backups that have been restored and verified, not only backups that completed. A backup that has never been restored is an unproven recovery point. Ask the client to confirm which PostgreSQL, ClickHouse and blob storage snapshots exist, their retention, and the date of the last successful test restore. Without this, a failed migration has no tested way back.
Supply an inventory of applications and SDK versions that send traces. Python SDK v5 and JS/TS SDK v6 require Langfuse v4.59.0 or later, so any older service must be scheduled for update first. List OTLP senders separately, since they depend on the /api/public/otel endpoint and their own instrumentation versions.
Finally, agree on change windows, approvers and a named owner for decisions. The owner settles trade-offs such as pausing ingestion during backfill or accepting a longer window. Approvers sign off on production changes. Without a named owner, open questions about scope and rollback stall the work, and the upgrade slips into an unplanned window.
Frequently asked questions
What drives the cost of a Langfuse upgrade and how do I get a quote?
The cost follows the written scope, and the scope is set by the upgrade path, the number of environments and the state of your data stores. Cost drivers include:
- Whether the move is a minor update or a major upgrade such as v3 to v4, which has its own migration guide.
- Data store versions. The v3 to v4 guide requires ClickHouse 25.12 or later (26.4 recommended), PostgreSQL 15 or later and Redis 7.0 or later.
- Backfill headroom. The guide advises about 3x ClickHouse disk headroom when backfilling historic data.
- Helm chart changes, SDK alignment and custom code.
To get a quote, send your current versions, deployment type, data volumes, environments and any SSO or Enterprise features in use. DeployOpen does not publish a price list. The quote follows from the written scope.
How long does a Langfuse upgrade project take?
No fixed duration is given until the environment is scoped. The timeline depends on your current version, whether you run Docker Compose on a single VM or Kubernetes with Helm or Terraform, how much ClickHouse data must be backfilled, how many environments need testing and when your change windows fall. Most engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts. Ask for the timeline to be stated in that written scope, with the assumptions behind it listed.
Can our own team upgrade Langfuse without outside help?
Often yes, if your team has the skills and time to test each step. Langfuse states that updates within a major version are non-disruptive and apply database migrations automatically at startup, so minor updates are the simplest case. Major upgrades follow dedicated migration guides and involve data store version checks, the Helm chart upgrade for bundled data stores, SDK version alignment and, for v4, a new observations-first ClickHouse data model with backfill. Your team should be ready to back up data, test in staging and roll back before choosing to go alone.
Does upgrading Langfuse require an Enterprise license key?
No. Langfuse states that all core features and APIs are available in the MIT-licensed open source version without limits, and an upgrade does not add a license requirement. A key is needed only for specific features, including project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side data masking, UI customization, organization creators, the org management API with SCIM and the instance management API. Code under the ee/ directories falls under a separate enterprise license. Check which of these features you use before and after the upgrade, and confirm the licensing position for your version.
What does support cover after go-live, compared with Langfuse Enterprise?
Support after go-live is defined in the written scope of your engagement or retainer, so confirm the exact services and response commitments there. DeployOpen offers ongoing support, upgrades and continuous testing as retainers. Langfuse's Self-Hosted Enterprise plan is a custom-priced plan from Langfuse that adds a named support engineer, solutions architect access and a support SLA. Those items come from Langfuse, not DeployOpen. If you need a named Langfuse engineer or a Langfuse SLA, buy that plan from Langfuse separately, and ask DeployOpen to confirm how its retainer fits alongside it.
Does DeployOpen issue certifications or audit reports for Langfuse?
No. DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies do that work. DeployOpen can prepare systems, controls and evidence for compliance assessments, such as upgrade records, backup test results, change logs and access configuration. Before the work starts, ask your auditor which evidence they need, and confirm that the written scope includes producing it.
How DeployOpen delivers upgrade and support work
DeployOpen plans, implements, upgrades, documents and supports self-hosted Langfuse inside your own cloud accounts, data centers or air-gapped networks. We treat each Langfuse upgrade as a scoped change with written deliverables, tested in a non-production environment before it reaches production.
How we scope
- Written scope states which Langfuse version you run today and which target version the work covers.
- Scope lists the data stores in use, including PostgreSQL, ClickHouse, Redis or Valkey and S3-compatible blob storage.
- Scope records whether you run Helm with bundled data stores, which affects the chart upgrade sequence.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before work starts.
How we build
- We check version requirements for each data store against the target Langfuse release before any change is made.
- We rehearse the upgrade in a non-production environment that mirrors your production topology and configuration.
- We verify SDK compatibility for the Python and JS/TS clients your applications use, against the target Langfuse version.
- We plan ClickHouse disk headroom and backfill timing for any major upgrade that rebuilds historic data, and confirm it with you.
How we hand over
- You receive a runbook covering the upgrade steps, rollback points, verification checks and the owner for each step.
- Post-upgrade tests confirm tracing ingestion, the UI, API access and prompt management work as expected.
- Configuration, Helm values and infrastructure changes are documented in your repository so your team can reproduce them.
- A short walkthrough with your platform and application teams explains what changed and what to watch after cutover.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped in writing like other engagements.
- Support covers planning for the next Langfuse release, including major version guides and data store version changes.
- Retainer scope should state response expectations, which we confirm in writing during quoting rather than assume.
- Ask your Langfuse vendor which support tier applies to your deployment, since self-hosted enterprise plans differ from the open source plan.
