LibreChat/helm/librechat

LibreChat Helm Chart

This Librechat Helm Chart provides an easy, light weight template to deploy LibreChat on Kubernetes

Variables

In this Chart, LibreChat will only work with environment Variables. You can Specify Vars and Secret using an existing Secret (This can be generated by creating an Env File and converting it to a Kubernetes Secret --from-env-file)

Setup

1. Generate Variables Generate CREDS_KEY, JWT_SECRET, JWT_REFRESH_SECRET and MEILI_MASTER_KEY using openssl rand -hex 32 and CREDS_IV using openssl rand -hex 16. place them in a secret like this (If you want to change the secret name, remember to change it in your helm values):

apiVersion: v1
kind: Secret
metadata:
  name: librechat-credentials-env
  namespace: <librechat-chart-namespace>
type: Opaque
stringData:
  CREDS_KEY: <generated value>
  JWT_SECRET: <generated value>
  JWT_REFRESH_SECRET: <generated value>
  MEILI_MASTER_KEY: <generated value>

2. Add Credentials to the Secret Dependant of the Model you want to use, create Credentials in your provider and add them to the Secret:

apiVersion: v1
kind: Secret
. . . .

  OPENAI_API_KEY: <your secret value>

3. Apply the Secret to the Cluster

4. Fill out values.yaml and apply the Chart to the Cluster

Admin Panel SSO

When deploying the admin panel at a separate URL, set librechat.adminPanelUrl to the external admin panel base URL. It may include a path, but it should not end with a trailing / because LibreChat appends /auth/... callback paths.

librechat:
  adminPanelUrl: https://admin.example.com/admin

This renders ADMIN_PANEL_URL for LibreChat's admin OAuth flow. For OpenID SSO, also register this LibreChat callback URL with your identity provider:

https://<librechat-domain>/api/admin/oauth/openid/callback

Langfuse Fanout

The chart can optionally deploy a Langfuse fanout gateway with an internal OpenTelemetry Collector sidecar. The gateway handles Langfuse media fanout and proxies traces to the collector; the collector forwards tenant-scoped Langfuse traces to both a central Langfuse project and the tenant Langfuse project. It is disabled by default.

When enabled, the chart also sets LANGFUSE_FANOUT_ENABLED and LANGFUSE_FANOUT_COLLECTOR_URL for the LibreChat app unless those values are already provided in librechat.configEnv.

Set librechat.configEnv.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED=true to keep central trace export flowing through the fanout gateway while disabling tenant trace and score export. When omitted, false, or blank, tenant export remains available if tenant keys and a known destination are configured.

Langfuse tenant base URLs are selected from the startup-configured destination map rendered into LibreChat and the fanout gateway. Tenant API keys can still be added through tenant app configuration at runtime without restarting either component. The internal collector provides trace memory limiting, batching, tenant routing, and removal of LibreChat-only routing attributes before export.

The fanout gateway stores one-time media upload plans in Redis so media create and byte-upload requests can land on different gateway replicas. Set langfuseFanout.redis.uri for an external Redis service, or enable the bundled Redis chart with redis.enabled=true and let the chart derive the internal URI. Scale the gateway manually with langfuseFanout.replicaCount; the chart does not create a fanout HPA. The internal collector receiver is bound to 127.0.0.1:4319 by default because only the gateway sidecar should send traces to it.

The gateway exposes Prometheus metrics at /metrics. Configure langfuseFanout.metrics.secret.name and .key to pass a bearer token secret to the gateway; if omitted, /metrics returns 401. Use langfuseFanout.service.annotations for scrape annotations when your cluster uses annotation-based discovery. The gateway container also has configurable /healthz liveness and readiness probes under langfuseFanout.

See otel/langfuse-fanout/README.md for the central Langfuse secret and values example.