diff --git a/content/docs/development/architecture.mdx b/content/docs/development/architecture.mdx index f5a59a22ce..35b35b4003 100644 --- a/content/docs/development/architecture.mdx +++ b/content/docs/development/architecture.mdx @@ -16,6 +16,7 @@ LibreChat is organized as a monorepo with clearly defined workspace boundaries: | `/packages/data-provider` | TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend | | `/client` | TypeScript/React | Frontend | `packages/data-provider`, `packages/client` | Frontend SPA | | `/packages/client` | TypeScript | Frontend | `packages/data-provider` | Shared frontend utilities | +| `/packages/chat` | TypeScript | Frontend | `packages/data-provider`, `packages/client` | `@librechat/chat`: chat state, transport, and message components moving out of `/client`; never imports the app | ### Key Principles @@ -37,8 +38,8 @@ LibreChat is organized as a monorepo with clearly defined workspace boundaries: | `npm run backend:dev` | Start backend with file watching (development) | | `npm run frontend:dev` | Start frontend dev server with HMR (port 3090, requires backend running) | -- Node.js: `v24.16.0` -- npm: `v11.16.0` +- Node.js: `v24.22.1` +- npm: `v11.13.0` - Database: MongoDB - Backend runs on `http://localhost:3080/`; frontend dev server on `http://localhost:3090/` diff --git a/content/docs/development/conventions.mdx b/content/docs/development/conventions.mdx index 68d0044a25..b25551fcd1 100644 --- a/content/docs/development/conventions.mdx +++ b/content/docs/development/conventions.mdx @@ -16,6 +16,7 @@ LibreChat is a monorepo. All new code should target the correct workspace: | `/packages/data-provider` | TypeScript | Shared | API types, endpoints, data-service — used by frontend and backend | | `/client` | TypeScript/React | Frontend | Frontend SPA | | `/packages/client` | TypeScript | Frontend | Shared frontend utilities | +| `/packages/chat` | TypeScript | Frontend | `@librechat/chat`: chat state, transport, and message components moving out of `/client`; never imports the app | - **All new backend code must be TypeScript** in `/packages/api`. - Keep `/api` changes to the absolute minimum (thin JS wrappers calling into `/packages/api`). @@ -31,7 +32,7 @@ LibreChat is a monorepo. All new code should target the correct workspace: - Use "clean code" principles: keep functions and modules small, adhere to the single responsibility principle, and write expressive and readable code. - Use meaningful and descriptive variable and function names. - Prioritize code readability and maintainability over brevity. -- Use the provided `.eslintrc` and `.prettierrc` files for consistent code formatting. +- Use the repository's `eslint.config.mjs` (ESLint flat config) and `.prettierrc` files for consistent code formatting. - Fix all formatting lint errors using auto-fix when available. All TypeScript/ESLint warnings and errors must be resolved. ### Naming and File Organization @@ -104,7 +105,7 @@ Imports are organized into three sections (in order): - Use try-catch blocks to catch and handle exceptions gracefully. - Implement proper error handling and consistently return appropriate error responses. - Use the logging system included in the `utils` directory to log important events and errors. -- Do JWT-based, stateless authentication using the `requireJWTAuth` middleware. +- Do JWT-based, stateless authentication using the `requireJwtAuth` middleware. ### File Structure diff --git a/content/docs/development/debugging.mdx b/content/docs/development/debugging.mdx index 191d8818ca..cb4daa7815 100644 --- a/content/docs/development/debugging.mdx +++ b/content/docs/development/debugging.mdx @@ -6,4 +6,9 @@ description: (WIP) Contributions are welcome -see also: [Logging System](/docs/configuration/logging) \ No newline at end of file +## Useful Settings + +- Set `DEBUG_CONSOLE=true` in `.env` for verbose server output in the console. +- Run `npm run backend:inspect` to start the backend with the Node.js inspector (`--inspect`) and `--expose-gc`, so you can attach a debugger. + +See also: [Logging System](/docs/configuration/logging) \ No newline at end of file diff --git a/content/docs/development/get_started.mdx b/content/docs/development/get_started.mdx index 1979042432..1717a1b568 100644 --- a/content/docs/development/get_started.mdx +++ b/content/docs/development/get_started.mdx @@ -7,8 +7,8 @@ description: Learn how to contribute using GitHub Desktop, VS Code extensions, a ## Requirements - [Git](https://git-scm.com/downloads) (Essential) -- [Node.js](https://nodejs.org/en/download) `v24.16.0` (Essential) -- npm `v11.16.0` (Essential) +- [Node.js](https://nodejs.org/en/download) `v24.22.1` (Essential) +- npm `v11.13.0` (Essential) - [MongoDB](https://www.mongodb.com/try/download/community) (Essential, for the database) - [Git LFS](https://git-lfs.com/) (Useful for larger files) - [GitHub Desktop](https://desktop.github.com/) (Optional) @@ -29,11 +29,13 @@ Install these extensions in VS Code: If you use `nvm`, install and select the recommended Node.js version before installing LibreChat: ```sh filename="Use Node.js 24" -nvm install 24.16.0 -nvm use 24.16.0 -npm install -g npm@11.16.0 +nvm install 24.22.1 +nvm use 24.22.1 +npm install -g npm@11.13.0 ``` +The `.nvmrc` file in the LibreChat repository is the source of truth for the Node.js version; running `nvm use` from the repository root selects it. + Verify your shell is using the expected versions: ```sh filename="Check Node.js and npm" @@ -42,23 +44,31 @@ npm -v ``` ```txt filename="Expected versions" -v24.16.0 -11.16.0 +v24.22.1 +11.13.0 ``` ### GitHub - Fork the LibreChat repository: [https://github.com/LibreChat-AI/LibreChat/fork](https://github.com/LibreChat-AI/LibreChat/fork) -- Create a branch on your fork, name it properly, and link it to the original repository. +- Clone your fork and add the original repository as `upstream`. Contributions branch from and target `dev`; `main` only moves at release time. + +```sh filename="Clone your fork and sync dev" +git clone https://github.com/username/LibreChat.git +cd LibreChat +git remote add upstream https://github.com/LibreChat-AI/LibreChat.git +git fetch upstream dev +git checkout -B dev upstream/dev +``` -- Download your new branch to your local PC +- Create a descriptive, slash-based branch off `dev`: -```sh filename="Download your LibreChat branch" -git clone -b branch-name https://github.com/username/LibreChat.git +```sh filename="Create your working branch" +git checkout -b new/feature/x ``` -> Replace `branch-name` and `username` with your details +> Replace `username` and the branch name with your details. Do not use `npm run update` to refresh a development branch; it is the self-host updater and checks out `main`. ### Open in VS Code @@ -89,6 +99,9 @@ git clone -b branch-name https://github.com/username/LibreChat.git - .env Configuration - Create the `.env` file. If you don't have one, duplicate `.env.example` and configure it. +- Git hooks + - `npm install` sets up husky pre-commit checks, which run the Static Checks CI job locally on the files in each commit (ESLint, Prettier, import order, circular dependencies). Set `HUSKY=0` to opt out, and run the checks by hand with `npm run static-checks`. + The default values in `.env.example` are usually fine, except for `MONGO_URI`. Provide your own. Make sure to install MongoDB and configure `MONGO_URI` correctly to connect to your MongoDB @@ -125,13 +138,13 @@ By running tests, ensure your contributions are robust and ready for integration ### Make a Commit -**Commits** mark logical checkpoints in development. Include clear messages explaining changes. +**Commits** mark logical checkpoints in development. Use conventional commit messages that begin with a type such as `feat`, `fix`, `docs`, or `refactor`, followed by a brief summary. **Example:** ```bash filename=" " git add . -git commit -m "Add login functionality" +git commit -m "feat: Add login functionality" ``` ### Push Changes @@ -146,25 +159,24 @@ git push origin feature-branch-name ### Create a Pull Request (PR) -**Pull Request** merges changes from a feature branch into the main branch. +**Pull Request** merges changes from a feature branch into the `dev` branch. -1. Pull latest changes from main branch and resolve conflicts. +1. Pull the latest changes from `dev` and resolve conflicts. 2. Push updated feature branch. 3. Ensure code follows project guidelines. **Example:** ```bash filename=" " -git checkout main -git pull origin main +git fetch upstream dev git checkout feature-branch-name -git rebase main +git rebase upstream/dev # Resolve conflicts if any git push origin feature-branch-name # Open PR on GitHub ``` -Access your repository in a browser and click "Contribute". +Access your fork in a browser and click "Contribute", and make sure the pull request targets `dev`. Provide a detailed PR description explaining changes and their value. Reference related issues. diff --git a/content/docs/development/index.mdx b/content/docs/development/index.mdx index a4032a9b9f..c9d06cee91 100644 --- a/content/docs/development/index.mdx +++ b/content/docs/development/index.mdx @@ -14,12 +14,12 @@ Use this toolchain for npm-based development: | Tool | Version | | ------- | ------------------------- | -| Node.js | `v24.16.0` | -| npm | `v11.16.0` | +| Node.js | `v24.22.1` | +| npm | `v11.13.0` | | MongoDB | Atlas or Community Server | Node 24 satisfies LibreChat's runtime needs for CommonJS interop with ESM-only packages, WebCrypto, -and the Fetch API. If your shell still reports an older Node version, run `nvm use 24.16.0` from the +and the Fetch API. If your shell still reports an older Node version, run `nvm use 24.22.1` from the LibreChat repository before installing dependencies. ## Work In The Right Workspace @@ -34,6 +34,7 @@ LibreChat is a monorepo. Pick the smallest workspace that owns the behavior you | `/packages/data-provider` | Shared API types, endpoints, query keys, and data-service functions | | `/client` | React application code | | `/packages/client` | Shared frontend utilities | +| `/packages/chat` | `@librechat/chat`: chat state, transport, and message components | ## Daily Commands @@ -50,7 +51,7 @@ LibreChat is a monorepo. Pick the smallest workspace that owns the behavior you - If you are new to repositories, forks, branches, and pull requests, start with **[GitHub's collaborative development guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models)**. - - Read the **[Contributor Guidelines](https://github.com/LibreChat-AI/LibreChat/blob/main/.github/CONTRIBUTING.md)** before opening a PR. + - Read the **[Contributor Guidelines](https://github.com/LibreChat-AI/LibreChat/blob/main/.github/CONTRIBUTING.md)** before opening a PR. Branch from `dev` and target `dev` with your pull request; `main` only moves at release time. - Use **[Contributor Setup](/docs/development/get_started)** for the full local setup flow. - Use **[Code Standards and Conventions](/docs/development/conventions)** for workspace boundaries, import order, typing, testing, and frontend rules. diff --git a/content/docs/development/testing.mdx b/content/docs/development/testing.mdx index e7503ac5b7..aa9388ac61 100644 --- a/content/docs/development/testing.mdx +++ b/content/docs/development/testing.mdx @@ -8,18 +8,23 @@ description: How to locally test the app during development. Before submitting your updates, verify they pass all unit tests. Follow these steps to run tests locally: -- Copy your `.env.example` file in the `/api` folder and rename it to `.env` +- Copy the example test environment file used by the API tests: - ```bash filename="create a /api/.env file" - cp .env.example ./api/.env + ```bash filename="create api/test/.env.test" + cp api/test/.env.test.example api/test/.env.test ``` -- Add `NODE_ENV=CI` to your `/api/.env` file - `npm run test:client` - `npm run test:api` - `npm run test:packages:api` - `npm run test:packages:data-provider` - `npm run test:packages:data-schemas` +- `npm run test:packages:chat` +- `npm run test:all` runs all of the suites above in sequence. + +### Static Checks + +Commits also run the Static Checks CI job locally through the husky pre-commit hook (set `HUSKY=0` to opt out). Run it by hand with `npm run static-checks`, or against a base branch with `npm run static-checks -- --against origin/dev`. `npm run static-checks:full` adds the slower gates (TypeScript, config migration tests, unused i18n keys, unused npm packages). ### Running Tests Per-Workspace @@ -30,6 +35,7 @@ cd api && npx jest cd packages/api && npx jest cd packages/data-provider && npx jest cd packages/data-schemas && npx jest +cd packages/chat && npx jest cd client && npx jest ``` diff --git a/content/docs/development/tools_and_plugins.mdx b/content/docs/development/tools_and_plugins.mdx index 9ec85f5726..3083c30eec 100644 --- a/content/docs/development/tools_and_plugins.mdx +++ b/content/docs/development/tools_and_plugins.mdx @@ -10,6 +10,10 @@ description: This doc shows you how to create custom plugins for LibreChat by ex # Making your own Tools/Plugins + + The steps below were written for an older version of the codebase. Tools now live in `api/app/clients/tools/structured/` and are registered in `api/app/clients/tools/util/handleTools.js`, so file names and function shapes in the examples may differ from the current tree. For new integrations, use [MCP servers](/docs/features/agents#model-context-protocol-mcp) or [Agents tools and actions](/docs/features/agents) instead. + + Please refer to the most recents tools used with assistants in `api/app/clients/tools/structured/` since plugins will be deprecated in favor of tools in the near future @@ -49,7 +53,7 @@ Here are the key takeaways for creating your own plugin: Remember, the key to creating a custom plugin is to extend the `Tool` class and implement the `_call` method. The `_call` method is where you define what your plugin does. You can also define helper methods and properties in your class to support the functionality of your plugin. -**Note: You can find all the files mentioned in this guide in the `.\api\app\langchain\tools` folder.** +**Note: You can find all the files mentioned in this guide in the `api/app/clients/tools` folder.** --- @@ -57,7 +61,7 @@ Remember, the key to creating a custom plugin is to extend the `Tool` class and **Multi-Input Plugins** -If you would like to make a plugin that would benefit from multiple inputs from the LLM, instead of a singular input string as we will review, you need to make a LangChain **[StructuredTool](https://blog.langchain.dev/structured-tools/)** instead. A detailed guide for this is in progress, but for now, you can look at how I've made StructuredTools in this directory: `api\app\clients\tools\structured\`. This guide is foundational to understanding StructuredTools, and it's recommended you continue reading to better understand LangChain tools first. The blog linked above is also helpful once you've read through this guide. +If you would like to make a plugin that would benefit from multiple inputs from the LLM, instead of a singular input string as we will review, you need to make a LangChain **[StructuredTool](https://blog.langchain.dev/structured-tools/)** instead. A detailed guide for this is in progress, but for now, you can look at how I've made StructuredTools in this directory: `api/app/clients/tools/structured/`. This guide is foundational to understanding StructuredTools, and it's recommended you continue reading to better understand LangChain tools first. The blog linked above is also helpful once you've read through this guide. --- @@ -160,7 +164,7 @@ class StableDiffusionAPI extends Tool { ## Step 5: Export Your Plugin and import into handleTools.js -**This process will be somewhat automated in the future, as long as you have your plugin/tool in `api\app\langchain\tools`** +**This process will be somewhat automated in the future, as long as you have your plugin/tool in `api/app/clients/tools`** ```javascript // Export @@ -168,8 +172,8 @@ module.exports = StableDiffusionAPI ``` ```js -/* api\app\langchain\tools\handleTools.js */ -const StableDiffusionAPI = require('./StableDiffusion'); +/* api/app/clients/tools/util/handleTools.js */ +const StableDiffusionAPI = require('../StableDiffusion'); ... ``` @@ -233,7 +237,7 @@ module.exports = { ## Step 7: Add your Plugin to manifest.json -**This process will be somehwat automated in the future along with step 5, as long as you have your plugin/tool in `api\app\langchain\tools`, and your plugin can be initialized with the default method** +**This process will be somehwat automated in the future along with step 5, as long as you have your plugin/tool in `api/app/clients/tools`, and your plugin can be initialized with the default method** ```json { diff --git a/content/docs/local/docker.mdx b/content/docs/local/docker.mdx index 164bb62674..484bcfe744 100644 --- a/content/docs/local/docker.mdx +++ b/content/docs/local/docker.mdx @@ -23,11 +23,11 @@ If you use Docker Desktop, it runs containers inside its own virtual machine, so If you connect LibreChat to models running on the same machine, such as [Ollama](/docs/configuration/librechat_yaml/ai_endpoints/ollama), size the hardware for the model you choose. That model runtime needs far more memory, and often a GPU, than LibreChat does. - + -Mac computers with Apple Silicon (M1, M2, M3, M4) processors do not support AVX instructions, which are required by the default MongoDB image used in LibreChat's Docker Compose setup. If you're on an M-series Mac, MongoDB will crash on startup. +The MongoDB image used by LibreChat's default Docker Compose setup requires a CPU with AVX instructions. On older x86 CPUs without AVX (and on some virtual machines that do not expose AVX to the guest), MongoDB crashes on startup. -**Fix:** Create a `docker-compose.override.yml` to use an older, compatible MongoDB image: +**Fix:** Create a `docker-compose.override.yml` to use an older MongoDB image that does not require AVX: ```yaml filename="docker-compose.override.yml" services: @@ -88,11 +88,11 @@ Open your browser and visit [http://localhost:3080](http://localhost:3080). You -In an unscoped single-tenant deployment, the first account you register becomes the admin account. There are no default credentials -- you create your own username and password during registration. Tenant-scoped deployments do not auto-promote the first user in each tenant; provision tenant administrators through a trusted administrative flow. +In an unscoped single-tenant deployment, the first account you register becomes the admin account. There are no default credentials; you create your own username and password during registration. Tenant-scoped deployments do not auto-promote the first user in each tenant; provision tenant administrators through a trusted administrative flow. -Click **Register** to create your account, then follow [Your First Chat](/docs/quick_start/first_chat) to add a model API key and send your first message. +Click **Sign up** to create your account, then follow [Your First Chat](/docs/quick_start/first_chat) to add a model API key and send your first message. @@ -136,6 +136,12 @@ You may need to prefix commands with `sudo` according to your environment permis + + +The repository's `npm run update:docker` script rebuilds locally built images but does not pull the prebuilt images that the default `docker-compose.yml` uses, so follow the manual steps below to update a default install. + + + ```bash filename="Stop the running container(s)" docker compose down ``` @@ -167,16 +173,24 @@ docker compose up If you see an error like `bind: address already in use` for port 3080, another application is using that port. -Either stop the conflicting application, or change the port in `docker-compose.override.yml`: +Either stop the conflicting application, or change the port LibreChat uses. The default `docker-compose.yml` publishes `"${PORT}:${PORT}"`, and ports added in an override file are appended to that list instead of replacing it, so an override alone does not free port 3080. + +The simplest fix is to set `PORT` in your `.env` file, which changes both the port LibreChat listens on and the published port: + +```bash filename=".env" +PORT=3081 +``` + +Alternatively, with Docker Compose 2.24.4 or later, replace the published port in `docker-compose.override.yml` with the `!override` tag (the container keeps listening on 3080): ```yaml filename="docker-compose.override.yml" services: api: - ports: + ports: !override - "3081:3080" ``` -Then visit `http://localhost:3081` instead. +Restart with `docker compose down && docker compose up -d`, then visit `http://localhost:3081` instead. ### Container Crashes on Startup @@ -188,7 +202,7 @@ docker compose logs api Common causes: -- Invalid `librechat.yaml` syntax -- validate with the [YAML Validator](/toolkit/yaml_checker) +- Invalid `librechat.yaml` syntax: validate with the [YAML Validator](/toolkit/yaml_checker) - Missing `.env` file -- ensure `.env` exists in the project root - Docker not running -- ensure Docker Desktop is open and running diff --git a/content/docs/local/helm_chart.mdx b/content/docs/local/helm_chart.mdx index ef0dc13f25..372c3ac792 100644 --- a/content/docs/local/helm_chart.mdx +++ b/content/docs/local/helm_chart.mdx @@ -80,10 +80,6 @@ See [Redis health checks](/docs/configuration/redis#health-checks) for what each ## Install Helm Chart - -The v0.8.8 chart source defaults `librechat.configEnv` to null. If you have no ConfigMap environment overrides, set it explicitly to `{}` in your values file, or pass `--set-json 'librechat.configEnv={}'` to `helm install` or `helm template`; otherwise the template's `dig` lookups can fail. Keep credentials in the named Secret. This is a rendering workaround, not a reason to disable the Secret requirement. - - To install the helm chart run: `helm install oci://ghcr.io/librechat-ai/librechat-chart/librechat` @@ -100,9 +96,9 @@ Similar to other Helm charts, there exists a [values file](https://github.com/Li 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 ` +Install the Helm chart: `helm install librechat oci://ghcr.io/librechat-ai/librechat-chart/librechat --values ` -Once the release is up and the service is reachable, follow [Your First Chat](/docs/quick_start/first_chat) to register an account, add a model API key, and send your first message. +Once the release is up and the service is reachable, follow [Your First Chat](/docs/quick_start/first_chat) to create an account, add a model API key, and send your first message. ## Uninstall the Helm Chart @@ -110,6 +106,45 @@ To uninstall the Helm Chart: `helm uninstall ` 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/-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: + +```bash +kubectl get secret -mongodb -o jsonpath='{.data.mongodb-root-password}' | base64 -d +helm upgrade ... --set-string mongodb.auth.rootPassword= +``` + +Redis needs `--set-string redis.auth.password=` the same way (`redis-password` in the `-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=`. + +### 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: "", pwd: "", roles: ["root"]})'` (`` is `mongodb.auth.rootUser`, `root` by default). Then upgrade with `--set-string mongodb.auth.rootPassword=` (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](/docs/features/admin_panel). + +```yaml +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. diff --git a/content/docs/local/npm.mdx b/content/docs/local/npm.mdx index c872b2502f..9975ab9b8d 100644 --- a/content/docs/local/npm.mdx +++ b/content/docs/local/npm.mdx @@ -8,8 +8,8 @@ For most scenarios, Docker Compose is the recommended installation method due to ## Prerequisites -- Node.js `v24.16.0`: [https://nodejs.org/en/download](https://nodejs.org/en/download) -- npm `v11.16.0` +- Node.js `v24.22.1`: [https://nodejs.org/en/download](https://nodejs.org/en/download) +- npm `v11.13.0` - LibreChat uses CommonJS (CJS) and openid-client v6; Node 24 satisfies the required CJS/ESM interop, WebCrypto, and Fetch API runtime support. - Git: https://git-scm.com/download/ @@ -22,15 +22,15 @@ For most scenarios, Docker Compose is the recommended installation method due to If you use `nvm`, install and select the recommended Node.js version, then update npm: ```bash filename="Use Node.js 24 and npm 11" -nvm install 24.16.0 -nvm use 24.16.0 -npm install -g npm@11.16.0 +nvm install 24.22.1 +nvm use 24.22.1 +npm install -g npm@11.13.0 node -v npm -v ``` -You should see `v24.16.0` for Node.js and `11.16.0` for npm before installing LibreChat -dependencies. +You should see `v24.22.1` for Node.js and `11.13.0` for npm before installing LibreChat +dependencies. The `.nvmrc` file in the LibreChat repository is the source of truth for the Node.js version, so `nvm use` run from the repository root selects the right one. ## Installation Steps @@ -52,12 +52,8 @@ cp .env.example .env > **Note:** **If you're using Windows 10, you might need to use `copy` instead of `cp`.** -```bash filename="Update the MONGO_URI" -Important: Edit the newly created `.env` file to update the `MONGO_URI` with your own MongoDB instance URI. -``` - - Edit the newly created `.env` file to update the `MONGO_URI` with your own + Edit the newly created `.env` file and set `MONGO_URI` to the connection string of your own MongoDB instance. ### Build and Start diff --git a/content/docs/quick_start/custom_endpoints.mdx b/content/docs/quick_start/custom_endpoints.mdx index 49eb9cb007..f46f24f63b 100644 --- a/content/docs/quick_start/custom_endpoints.mdx +++ b/content/docs/quick_start/custom_endpoints.mdx @@ -155,12 +155,14 @@ Start with the server logs: docker compose logs api ``` -**But do not stop there.** LibreChat keeps a custom endpoint only if all of `name`, `baseURL`, `apiKey`, and `models` are present, and `models` has either `fetch: true` or a non-empty `default` list. An entry failing that check is removed from the endpoint list with **no error and no log line at all**: the provider simply never appears, and the logs look clean. +**But do not stop there.** LibreChat keeps a custom endpoint only if `name`, `baseURL`, `apiKey`, and `models` are all present. An entry missing any of them is removed from the endpoint list with **no error and no log line at all**: the provider simply never appears, and the logs look clean. + +A `models` block is different: `models.default` must list at least one model even when `fetch: true` is set. An empty or missing `default` is a validation error that stops startup. So when an endpoint is missing, check the block itself before hunting through logs: - Is every one of `name`, `baseURL`, `apiKey`, `models` spelled correctly? A single typo drops the whole entry. -- Does `models` have `fetch: true` or at least one entry under `default`? +- Does `models.default` list at least one model (required even with `fetch: true`)? - Is the block indented **inside** the `endpoints.custom` list, rather than at the top level? - Is the `name` unique? A second endpoint with the same name (case-insensitively) silently replaces the first. diff --git a/content/docs/remote/cloudflare.mdx b/content/docs/remote/cloudflare.mdx index dede3c9213..e39809f96c 100644 --- a/content/docs/remote/cloudflare.mdx +++ b/content/docs/remote/cloudflare.mdx @@ -24,7 +24,7 @@ description: Quick Guide to Domain Registration and Cloudflare Tunnel Configurat - If your domain was purchased via Cloudflare, this step is skipped as your domain is already configured to use Cloudflare's nameservers. - Log into your Cloudflare account and add your new domain. Follow the instructions to replace your domain's nameservers with those provided by Cloudflare, which is necessary for activating Cloudflare's services. -### Step 3: Create a Tunnel +### Step 2: Create a Tunnel @@ -57,12 +57,16 @@ description: Quick Guide to Domain Registration and Cloudflare Tunnel Configurat #### Configure your Tunnel -- Initiate a tunnel using either the Cloudflare dashboard under the "Tunnels" section +- Create the tunnel from the Cloudflare dashboard under the "Tunnels" section, then add a public hostname for your domain or subdomain. +- Set the service URL to the address where LibreChat is reachable from the machine running `cloudflared`: + - `http://localhost:3080` if you run LibreChat with the default `docker-compose.yml` or with npm. + - `http://localhost:80` if you run it with `deploy-compose.yml`, which serves LibreChat through its NGINX container on port 80. +- In your `.env` file, set `DOMAIN_CLIENT` and `DOMAIN_SERVER` to the public URL of the tunnel (for example `https://chat.example.com`), then restart LibreChat so links, cookies, and OAuth callbacks use the public hostname. ![image](https://github.com/danny-avila/LibreChat/assets/32828263/0232a545-115a-4c91-99e3-1240542bbea2) -### Step 6: Verify the Tunnel +### Step 3: Verify the Tunnel - Test the connection by accessing your domain/subdomain in a web browser, ensuring it resolves to your server via the Cloudflare Tunnel without errors. - Monitor your tunnel's performance and status directly from the Cloudflare dashboard under the "Tunnels" section. diff --git a/content/docs/remote/docker_linux.mdx b/content/docs/remote/docker_linux.mdx index fe13bcb618..3c5ef6c62d 100644 --- a/content/docs/remote/docker_linux.mdx +++ b/content/docs/remote/docker_linux.mdx @@ -148,7 +148,7 @@ npm -v ![image](https://github.com/danny-avila/LibreChat/assets/110412045/fbba1a38-95cd-4e8e-b813-04001bb82b25) -> Note: this may install old Node.js and npm versions. If you run LibreChat directly on the host, use Node.js `v24.16.0` with npm `v11.16.0`. For this Docker-based guide, the host Node.js version does not matter because LibreChat runs inside containers. +> Note: this may install old Node.js and npm versions. If you run LibreChat directly on the host, use Node.js `v24.22.1` with npm `v11.13.0`. For this Docker-based guide, the host Node.js version does not matter because LibreChat runs inside containers. **Ok, now that you have set up the Droplet, you will now setup the app itself** @@ -231,6 +231,14 @@ JWT_SECRET= JWT_REFRESH_SECRET= ``` +`deploy-compose.yml` also starts the [admin panel](/docs/features/admin_panel), which refuses to start without a session encryption key (at least 32 characters). Generate one with `openssl rand -hex 32` and add it to the same file: + +```bash +ADMIN_PANEL_SESSION_SECRET= +``` + +NGINX serves the panel on `admin.localhost` by default, which only resolves on the server itself. To reach it from your own machine, point a DNS record at the server, use that hostname as the panel's `server_name`, and set `ADMIN_PANEL_URL` in `.env` to the panel's public URL; see [NGINX](/docs/remote/nginx) for the server block. + Keep these values and the `librechat-data` volume private. Every replica must use the same permanent values. Losing the temporary file or changing established credentials can invalidate sessions and make encrypted records unreadable; LibreChat warns when active credential fingerprints no longer match the database marker. If you'd like to provide any credentials for all users of your instance to consume, you should add them while you're still editing this file: @@ -353,12 +361,12 @@ docker images -a --filter "reference=ghcr.io/librechat-ai/librechat*" --format " git pull ``` -```bash filename="Pull the latest LibreChat image"" +```bash filename="Pull the latest LibreChat image" docker compose -f ./deploy-compose.yml pull ``` ```bash filename="Start LibreChat" -docker compose -f ./deploy-compose.yml up +docker compose -f ./deploy-compose.yml up -d ``` ## Part IV: Editing the NGINX file (for custom domains and advanced configs) @@ -424,7 +432,7 @@ You should be all set! ## Part V: Use the Latest Stable Release instead of Latest Main Branch -By default, this setup will pull the latest updates to the main branch of Librechat. If you would rather have the latest "stable" release, which is defined by the [latest tags](https://github.com/LibreChat-AI/LibreChat/releases), you will need to edit deploy-compose.yml and commit your changes exactly as above in Part V. Be aware that you won't benefit from the latest feature as soon as they come if you do so. +By default, this setup will pull the latest updates to the main branch of Librechat. If you would rather have the latest "stable" release, which is defined by the [latest tags](https://github.com/LibreChat-AI/LibreChat/releases), you will need to edit deploy-compose.yml and commit your changes exactly as above in Part IV. Be aware that you won't benefit from the latest feature as soon as they come if you do so. Let's edit `deploy-compose.yml`: @@ -438,4 +446,4 @@ Change `librechat-dev-api` to `librechat-api`: image: registry.librechat.ai/librechat-ai/librechat-api:latest ``` -Stage and commit as in Part V, and you're all set! +Stage and commit as in Part IV, and you're all set! diff --git a/content/docs/remote/huggingface.mdx b/content/docs/remote/huggingface.mdx index 92180d5f71..fea6e129ee 100644 --- a/content/docs/remote/huggingface.mdx +++ b/content/docs/remote/huggingface.mdx @@ -32,8 +32,6 @@ You will need to fill these values: | --- | --- | | MONGO_URI | * use these instruction to get the string: https://librechat.ai/docs/configuration/mongodb/mongodb_atlas | | OPENAI_API_KEY | `user_provided` | -| BINGAI_TOKEN | `user_provided` | -| CHATGPT_TOKEN | `user_provided` | | ANTHROPIC_API_KEY | `user_provided` | | GOOGLE_KEY | `user_provided` | | CREDS_KEY | * see below | @@ -45,8 +43,7 @@ You will need to fill these values: > ⚠️ setting the API keys and token to `user_provided` allows you to provide them safely from the webUI -> * For `CREDS_KEY`, `CREDS_IV` and `JWT_SECRET` use this tool: **[Credentials Generator](/toolkit/creds_generator)** -> * Run the tool a second time and use the new `JWT_SECRET` value for the `JWT_REFRESH_SECRET` +> * For `CREDS_KEY`, `CREDS_IV`, `JWT_SECRET` and `JWT_REFRESH_SECRET` use this tool: **[Credentials Generator](/toolkit/creds_generator)** | Variables | Values | | --- | --- | diff --git a/content/docs/remote/nginx.mdx b/content/docs/remote/nginx.mdx index 64f2a532d5..9d9b8a305d 100644 --- a/content/docs/remote/nginx.mdx +++ b/content/docs/remote/nginx.mdx @@ -11,7 +11,7 @@ This guide covers the essential steps for securing your LibreChat deployment wit 1. A cloud server (e.g., AWS, Google Cloud, Azure, Digital Ocean). 2. A registered domain name. 3. Terminal access to your cloud server. -4. Node.js `v24.16.0` and npm `v11.16.0` if you run LibreChat directly on the host. +4. Node.js `v24.22.1` and npm `v11.13.0` if you run LibreChat directly on the host. ## Initial Setup @@ -63,6 +63,10 @@ client: 4. Commit the changes to a new Git branch. 5. Rebase the deployed instance: `npm run rebase:deployed` + + `client/nginx.conf` also contains a second `server` block that serves the bundled [admin panel](/docs/features/admin_panel) on `admin.localhost` and proxies it to the `admin-panel` container. For a public domain, change that `server_name` to the hostname you use for the panel (and mirror the commented SSL variant if you terminate HTTPS in this container). Also set `ADMIN_PANEL_URL` in `.env` to the panel's public URL (for example `https://admin.example.com`); otherwise the admin link and SSO sign-ins return to `http://admin.localhost`. The panel needs `ADMIN_PANEL_SESSION_SECRET` set in `.env`. + + ### Option B: Host-based Deployment without Docker If you're not using Docker, you can install and configure Nginx directly on the host: @@ -100,7 +104,7 @@ server { 1. Navigate to your application's directory: -```bash filename="Replace 'LibreChat' with your actual application directory. +```bash filename="Replace 'LibreChat' with your actual application directory." cd LibreChat ``` @@ -115,14 +119,14 @@ sudo docker compose -f ./deploy-compose.yml up -d If you set up nginx using the recommended Option A above, use these steps to renew the certificates: 1. Navigate to your application's directory -```bash filename="Replace 'LibreChat' with your actual application directory. +```bash filename="Replace 'LibreChat' with your actual application directory." cd LibreChat ``` 2. Stop your running Docker containers ```bash filename="Stop your application" -sudo docker compose -f ./deploy-compose.yml down -d +sudo docker compose -f ./deploy-compose.yml down ``` 3. renew certificates diff --git a/content/docs/remote/ngrok.mdx b/content/docs/remote/ngrok.mdx index 382d866cf1..9a22c01667 100644 --- a/content/docs/remote/ngrok.mdx +++ b/content/docs/remote/ngrok.mdx @@ -13,7 +13,13 @@ To use ngrok for tunneling your local server to the internet, follow these steps ## Docker Installation 1. Copy your auth token from: **[https://dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken)** -2. Open a terminal and run the following command: `docker run -d -it -e NGROK_AUTHTOKEN= ngrok/ngrok http 80` +2. Open a terminal and run the following command. Inside the ngrok container, `localhost` refers to the container itself, so the command points ngrok at the Docker host, where LibreChat publishes port 3080: + +```bash +docker run -d -it --add-host=host.docker.internal:host-gateway -e NGROK_AUTHTOKEN= ngrok/ngrok http host.docker.internal:3080 +``` + +The `--add-host` flag is needed on Linux; Docker Desktop on macOS and Windows already resolves `host.docker.internal`. If you run LibreChat with `deploy-compose.yml`, use `host.docker.internal:80` instead. ## Windows Installation @@ -48,3 +54,7 @@ You will see a link that can be used to access LibreChat. 7. In the terminal where you ran ngrok, enter the following command: `ngrok authtoken ` 8. If you haven't done so already, start LibreChat normally. 9. In the terminal where you ran ngrok, enter the following command: `./ngrok http 3080` + +## Update your .env + +Once ngrok shows your public URL, set `DOMAIN_CLIENT` and `DOMAIN_SERVER` in LibreChat's `.env` file to that URL (for example `https://example.ngrok-free.app`), then restart LibreChat so links, cookies, and OAuth callbacks use the public address. diff --git a/content/docs/remote/railway.mdx b/content/docs/remote/railway.mdx index 2d3fffd4ad..f137a6e51d 100644 --- a/content/docs/remote/railway.mdx +++ b/content/docs/remote/railway.mdx @@ -37,7 +37,7 @@ The default configuration will get you started, but for more advanced features, ### **Deploy** -Once you've filled in the required environment variables, click the "Deploy" button. Railway will handle the rest, including setting up a PostgreSQL database and building/deploying your LibreChat instance. +Once you've filled in the required environment variables, click the "Deploy" button. Railway will handle the rest, including provisioning the services defined in the template and building/deploying your LibreChat instance. ![image](https://github.com/danny-avila/LibreChat/assets/32828263/d94e20c6-0ae7-42af-8937-7fbd34d63a3b) diff --git a/content/docs/remote/traefik.mdx b/content/docs/remote/traefik.mdx index ee27a1a299..9c4a67c9cc 100644 --- a/content/docs/remote/traefik.mdx +++ b/content/docs/remote/traefik.mdx @@ -18,8 +18,6 @@ description: Learn how to use Traefik as a reverse proxy and load balancer to ex In your docker-compose.override.yml file, add the following configuration: ```yaml filename="docker-compose.override.yml" -version: '3' - services: api: labels: diff --git a/content/docs/toolkit/credentials-generator.mdx b/content/docs/toolkit/credentials-generator.mdx index b90087f9b0..8bb22d3903 100644 --- a/content/docs/toolkit/credentials-generator.mdx +++ b/content/docs/toolkit/credentials-generator.mdx @@ -8,3 +8,11 @@ import { CredentialsGeneratorMDX } from '@/components/tools/CredentialsGenerator Generate cryptographically secure random values for the required secrets in your LibreChat `.env` configuration file. Click **Generate** and then copy individual values or all of them at once. + +## Admin panel session secret + +If you run the bundled [admin panel](/docs/features/admin_panel) with `docker-compose.yml` or `deploy-compose.yml`, set `ADMIN_PANEL_SESSION_SECRET` in `.env` as well. The generator does not output it. It is a session encryption key of at least 32 characters, and the admin panel container refuses to start without it. Generate it in a terminal: + +```bash +openssl rand -hex 32 +``` diff --git a/content/docs/translation.mdx b/content/docs/translation.mdx index b36e993ab4..d2a47bca26 100644 --- a/content/docs/translation.mdx +++ b/content/docs/translation.mdx @@ -227,7 +227,7 @@ This image shows how a single interpolation is represented in a translation stri Now, look at the translation key `com_files_number_selected`, which includes two placeholders. The English version is: ```text -{{0}} of {{1}} item(s) selected +{{0}} of {{1}} items(s) selected ``` In the German translation, both placeholders must be preserved and positioned correctly: @@ -253,7 +253,7 @@ Open a new issue in our GitHub repository: [LibreChat Issues](https://github.com 2. **Select the New Language Request Template:** Use the **New Language Request** template and provide: - The full name of your language (e.g., Spanish, Mandarin). - - The [ISO 639-1](https://www.w3schools.com/tags/ref_language_codes.asp) code for your language (e.g., `es` for Spanish). + - The [ISO 639-1](https://www.w3schools.com/tags/ref_language_codes.asp) code for your language (e.g., `es` for Spanish). Some locale codes, such as `zh-Hans` and `pt-BR`, are not pure ISO 639-1 codes; they add a script or region subtag, so include that if your language needs it. 3. **Collaborate with Maintainers:** Our maintainers will review your request and work with you to integrate the new language. Once approved, your language will appear in the translation progress table, and you can start contributing.