Skip to main content

LibreChat is joining ClickHouse. Learn more

LibreChat

Helm Chart

Instructions for deploying LibreChat on Kubernetes using Helm

Please follow this guidance to deploy LibreChat on Kubernetes using Helm, adjusting as needed for your specific use case. Other Helm charts contributed by the community are listed below in the Community Helm Charts section.

Prerequisites

  • A running Kubernetes cluster
  • Local installations of kubectl and Helm

Configuration

  1. Use the Credentials Generator to generate secure values for CREDS_KEY, CREDS_IV, JWT_SECRET, JWT_REFRESH_SECRET and MEILI_MASTER_KEY. Place them in a Kubernetes Secret like this (if you change the secret name, remember to update your Helm values):
apiVersion: v1
kind: Secret
metadata:
  name: librechat-credentials-env
  namespace: <librechat-chart-namespace>
type: Opaque
stringData:
  CREDS_KEY: <generated value>
  CREDS_IV: <generated value>
  JWT_SECRET: <generated value>
  JWT_REFRESH_SECRET: <generated value>
  MEILI_MASTER_KEY: <generated value>

Use permanent values and mount the same Secret into every replica. Do not rely on process-local or ephemeral filesystem credentials in Kubernetes: changing these values can invalidate sessions and make existing encrypted records unreadable.

The Secret named by global.librechat.existingSecretName must exist before the LibreChat container starts. A missing or misspelled named Secret blocks pod startup instead of falling back to temporary pod-local credentials. The chart does not validate the keys inside it, so ensure it contains CREDS_KEY, CREDS_IV, JWT_SECRET, and JWT_REFRESH_SECRET.

Set global.librechat.existingSecretName: "" only when every LibreChat credential is supplied another way. librechat.configEnv accepts string values for ConfigMap data, while global.librechat.env accepts Kubernetes environment entries such as valueFrom.secretKeyRef. Prefer Secret references for production.

Bundled Meilisearch has a separate dependency on meilisearch.auth.existingMasterKeySecret, which defaults to librechat-credentials-env and must contain the same MEILI_MASTER_KEY supplied to LibreChat. Clearing the LibreChat Secret reference does not clear this Meilisearch reference. If bundled Meilisearch is disabled, configure the external search service and its credentials separately. 2. Add to this same secret any required API keys for LLM providers:

apiVersion: v1
kind: Secret
metadata:
  name: librechat-credentials-env
  namespace: <librechat-chart-namespace>
type: Opaque
stringData:
  CREDS_KEY: <same generated value as above>
  CREDS_IV: <same generated value as above>
  JWT_SECRET: <same generated value as above>
  JWT_REFRESH_SECRET: <same generated value as above>
  MEILI_MASTER_KEY: <same generated value as above>
  OPENAI_API_KEY: <your secret value>
  1. Apply the Secret to the Cluster:

Save the complete Secret manifest as librechat-credentials.yaml, using the intended namespace, then apply it:

kubectl apply -f librechat-credentials.yaml
  1. Point the probes at the dedicated endpoints. The chart's default probes use /health, which stays 200 while Redis is down, so a pod that cannot sign anyone in keeps receiving traffic. Override them in your values file so readiness follows Redis and liveness does not:
livenessProbe:
  httpGet:
    path: /livez
    port: 3080
readinessProbe:
  httpGet:
    path: /readyz
    port: 3080

See Redis health checks for what each endpoint reports.

Install Helm Chart

To install the helm chart run:

helm install <deployment-name> oci://ghcr.io/librechat-ai/librechat-chart/librechat

Development version

In the repo's root directory, run:

helm install <deployment-name> ./helm/librechat

Similar to other Helm charts, there exists a values file that outlines the default settings and indicates which configuration options can be modified.

Create a values.yaml file populated with the values you want to modify from the default.

Install the Helm chart: helm install librechat oci://ghcr.io/librechat-ai/librechat-chart/librechat --values <values-override-file>

Once the release is up and the service is reachable, follow Your First Chat to create an account, add a model API key, and send your first message.

Uninstall the Helm Chart

To uninstall the Helm Chart: helm uninstall <deployment-name>

Example: helm uninstall librechat

Upgrading to chart 3.x

Chart 3.0.0 enables authentication on the bundled MongoDB and Redis by default. Their generated passwords stay in the subchart Secrets and reach LibreChat through secretKeyRef (MONGODB_ROOT_PASSWORD, REDIS_PASSWORD), and MONGO_URI is assembled in the Deployment. To use your own database, set librechat.configEnv.MONGO_URI (or REDIS_URI). Set mongodb.auth.enabled=false or redis.auth.enabled=false only to restore the old unauthenticated behavior. Custom root passwords must be URL-safe because they are placed in MONGO_URI.

If MONGO_URI, REDIS_URI or REDIS_PASSWORD comes from the Secret named by global.librechat.existingSecretName, set librechat.injectBundledCredentials.mongodb=false (for MONGO_URI) or librechat.injectBundledCredentials.redis=false (for REDIS_URI or REDIS_PASSWORD). The chart cannot see inside that Secret, and the generated values would otherwise override it. The two settings are independent. If you keep the bundled MongoDB or Redis, it must use the same password as your Secret: point mongodb.auth.existingSecret or redis.auth.existingSecret at it, or set the matching auth password, or the database keeps its generated password and LibreChat fails to authenticate. The credentials are read when a pod starts, so after rotating a database password, restart every Deployment that reads it with kubectl rollout restart deployment/<release>-librechat.

Keeping the generated passwords across upgrades

With the defaults, the subcharts generate the passwords on first install, and the MongoDB subchart refuses later upgrades that do not repeat them ("PASSWORDS ERROR"). Read the current values and pass them on every helm upgrade, or point mongodb.auth.existingSecret and redis.auth.existingSecret at Secrets you manage:

kubectl get secret <release>-mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d
helm upgrade <release> ... --set-string mongodb.auth.rootPassword=<password>

Redis needs --set-string redis.auth.password=<password> the same way (redis-password in the <release>-redis Secret). With mongodb.architecture=replicaset, also keep the replica set key: read mongodb-replica-set-key from the same Secret and pass it as --set-string mongodb.auth.replicaSetKey=<key>.

Upgrading from an unauthenticated bundled MongoDB

Releases installed before authentication became the default have a data volume with no root user, and the persisted data is not re-initialized on upgrade, so LibreChat cannot authenticate after helm upgrade. Pick one path:

  1. Keep the old behavior: --set mongodb.auth.enabled=false.
  2. Create the root user first. On the running pre-upgrade pod, run mongosh admin --eval 'db.createUser({user: "<rootUser>", pwd: "<password>", roles: ["root"]})' (<rootUser> is mongodb.auth.rootUser, root by default). Then upgrade with --set-string mongodb.auth.rootPassword=<password> (URL-safe) and the same mongodb.auth.rootUser if you changed it. Keep the same password on every later upgrade. An upgrade without mongodb.auth.rootPassword is refused by the MongoDB subchart ("PASSWORDS ERROR") because no Secret exists yet.

The chart cannot detect this case at render time, so NOTES.txt prints a notice on every upgrade with authentication enabled.

Ingress TLS

The ingress is enabled by default. Set ingress.tls (a secretName and hosts) for any non-local install; helm install prints a warning for every ingress host that no ingress.tls entry covers.

Admin panel URL

Set librechat.adminPanelUrl to the admin panel base URL used for OAuth/SSO redirects. It may include a path but must not end with a trailing /. See Admin Panel.

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

Migrate 1.x -> 2.x

If you used the chart before version 2.x you may need to update the value structure.

  1. Move Config to librechat.configEnv:
- env:
-     ALLOW_EMAIL_LOGIN: "true"
-     ALLOW_REGISTRATION: "true"
+ librechat:
+   configEnv:
+     ALLOW_REGISTRATION: "true"
+     ALLOW_EMAIL_LOGIN: "true"
  1. Consolidate all Secret values to a single Secret as described in Configuration Step 1.
  2. To leverage an external MongoDB instance, refer to the values file of the Chart, deactivate the components accordingly and change the FQDN of the Mongodb instance. This is recommended if data already exists in this externally managed MongoDB instance.

Community Helm Charts

How is this guide?