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
kubectland Helm
Configuration
- Use the Credentials Generator to generate secure values for
CREDS_KEY,CREDS_IV,JWT_SECRET,JWT_REFRESH_SECRETandMEILI_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>- 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- Point the probes at the dedicated endpoints. The chart's default probes use
/health, which stays200while 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: 3080See 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:
- Keep the old behavior:
--set mongodb.auth.enabled=false. - Create the root user first. On the running pre-upgrade pod, run
mongosh admin --eval 'db.createUser({user: "<rootUser>", pwd: "<password>", roles: ["root"]})'(<rootUser>ismongodb.auth.rootUser,rootby default). Then upgrade with--set-string mongodb.auth.rootPassword=<password>(URL-safe) and the samemongodb.auth.rootUserif you changed it. Keep the same password on every later upgrade. An upgrade withoutmongodb.auth.rootPasswordis 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/adminMigrate 1.x -> 2.x
If you used the chart before version 2.x you may need to update the value structure.
- Move Config to librechat.configEnv:
- env:
- ALLOW_EMAIL_LOGIN: "true"
- ALLOW_REGISTRATION: "true"
+ librechat:
+ configEnv:
+ ALLOW_REGISTRATION: "true"
+ ALLOW_EMAIL_LOGIN: "true"- Consolidate all Secret values to a single Secret as described in Configuration Step 1.
- 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
- Blue Atlas Helm Charts # deprecated now that LibreChat provides an official chart
- Submitted by @dimaby on GitHub: PR #2879
How is this guide?