From 585d63b7834fe6c8b3b94d24cbd0befa65700418 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Fri, 16 Oct 2026 20:03:29 +0200 Subject: [PATCH 1/4] docs: add system requirements to local installation guides Feedback: 1560510614588358778 --- content/docs/local/docker.mdx | 11 +++++++++++ content/docs/local/npm.mdx | 1 + 2 files changed, 12 insertions(+) diff --git a/content/docs/local/docker.mdx b/content/docs/local/docker.mdx index 48282d86e..8bc07734a 100644 --- a/content/docs/local/docker.mdx +++ b/content/docs/local/docker.mdx @@ -13,6 +13,17 @@ For most scenarios, Docker Compose is the recommended installation method due to Docker Desktop is recommended for most users. For remote server installations, see the [Ubuntu Docker Deployment Guide](/docs/remote/docker_linux). +### System Requirements + +LibreChat does not run AI models itself; it sends requests to the providers you configure, so it does not need a GPU. The [minimum requirements](/docs/remote#minimum-requirements) are the same locally as on a server: + +- 1 GiB RAM +- 1 vCPU + +The default Docker Compose file starts several containers alongside LibreChat: MongoDB, Meilisearch (conversation search), the RAG API with a PostgreSQL/pgvector database (file search), and the admin panel. With all of them running, plan for at least 2 GB of RAM available to Docker for smoother operation. On Docker Desktop, check the memory limit under **Settings > Resources**. + +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. diff --git a/content/docs/local/npm.mdx b/content/docs/local/npm.mdx index 44ac73d60..9c0914371 100644 --- a/content/docs/local/npm.mdx +++ b/content/docs/local/npm.mdx @@ -16,6 +16,7 @@ For most scenarios, Docker Compose is the recommended installation method due to - MongoDB (Atlas or Community Server) - [MongoDB Atlas](/docs/configuration/mongodb/mongodb_atlas) - [MongoDB Community Server](/docs/configuration/mongodb/mongodb_community) +- At least 1 GiB RAM and 1 vCPU. See [System Requirements](/docs/local/docker#system-requirements) for what to plan for when you add more services or run models locally. If you use `nvm`, install and select the recommended Node.js version, then update npm: From 02d1052db819663b91eb20a718a6e2863d4d176d Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Sun, 18 Oct 2026 14:29:51 +0200 Subject: [PATCH 2/4] docs: separate Docker Desktop host requirements from container minimums --- content/docs/local/docker.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/content/docs/local/docker.mdx b/content/docs/local/docker.mdx index 8bc07734a..893e0153f 100644 --- a/content/docs/local/docker.mdx +++ b/content/docs/local/docker.mdx @@ -15,12 +15,11 @@ Docker Desktop is recommended for most users. For remote server installations, s ### System Requirements -LibreChat does not run AI models itself; it sends requests to the providers you configure, so it does not need a GPU. The [minimum requirements](/docs/remote#minimum-requirements) are the same locally as on a server: +LibreChat does not run AI models itself; it sends requests to the providers you configure, so it does not need a GPU. -- 1 GiB RAM -- 1 vCPU +Your computer must first meet Docker Desktop's own requirements. At the time of writing, Docker Desktop needs at least 4 GB of system RAM on [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) and [Linux](https://docs.docker.com/desktop/setup/install/linux/), and 8 GB on [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), plus hardware virtualization. Check the linked pages for the current requirements. -The default Docker Compose file starts several containers alongside LibreChat: MongoDB, Meilisearch (conversation search), the RAG API with a PostgreSQL/pgvector database (file search), and the admin panel. With all of them running, plan for at least 2 GB of RAM available to Docker for smoother operation. On Docker Desktop, check the memory limit under **Settings > Resources**. +On top of that, LibreChat's containers need at least 1 GiB of RAM and 1 vCPU, the same [minimum](/docs/remote#minimum-requirements) as on a server. The default Docker Compose file starts MongoDB, Meilisearch (conversation search), and the RAG API with a PostgreSQL/pgvector database (file search) alongside LibreChat. It also defines the admin panel, which only starts once `ADMIN_PANEL_SESSION_SECRET` is set in `.env` (see [Admin Panel](/docs/features/admin_panel)). With everything running, give Docker at least 2 GB of memory for smoother operation. On Docker Desktop, check the memory limit under **Settings > Resources**. 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. From f51c9a7a17eab6956d730f9def2374244ae071cc Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Sun, 18 Oct 2026 14:37:59 +0200 Subject: [PATCH 3/4] test: cover local installation system requirements --- e2e/local-system-requirements.spec.ts | 71 +++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 e2e/local-system-requirements.spec.ts diff --git a/e2e/local-system-requirements.spec.ts b/e2e/local-system-requirements.spec.ts new file mode 100644 index 000000000..a9a431821 --- /dev/null +++ b/e2e/local-system-requirements.spec.ts @@ -0,0 +1,71 @@ +import { expect, test, type Page } from '@playwright/test' + +const DOCKER = '/docs/local/docker' + +function body(page: Page) { + return page.locator('#nd-page') +} + +function requirements(page: Page) { + return body(page).locator('h3#system-requirements ~ p') +} + +test.describe('Local installation system requirements', () => { + test('@scenario:docker-guide-separates-host-and-container-requirements a Docker reader sees Docker Desktop host minimums apart from the container minimum', async ({ + page, + }) => { + await page.goto(DOCKER) + + await expect( + body(page).getByRole('heading', { level: 3, name: 'System Requirements' }), + ).toBeVisible() + + // Docker Desktop's own host requirement comes first, per platform, so the + // 1 GiB container minimum is never read as the whole machine's requirement. + for (const [name, href] of [ + ['macOS', 'https://docs.docker.com/desktop/setup/install/mac-install/'], + ['Linux', 'https://docs.docker.com/desktop/setup/install/linux/'], + ['Windows', 'https://docs.docker.com/desktop/setup/install/windows-install/'], + ]) { + await expect( + requirements(page).getByRole('link', { name, exact: true }).first(), + ).toHaveAttribute('href', href) + } + await expect(requirements(page).filter({ hasText: 'at least 4 GB of system RAM' })).toHaveCount( + 1, + ) + await expect(requirements(page).filter({ hasText: '1 GiB of RAM and 1 vCPU' })).toHaveCount(1) + + const minimum = requirements(page).getByRole('link', { name: 'minimum', exact: true }) + await expect(minimum).toHaveAttribute('href', '/docs/remote#minimum-requirements') + + await page.goto('/docs/remote') + await expect(page.locator('#minimum-requirements')).toBeVisible() + }) + + test('@scenario:docker-guide-admin-panel-needs-session-secret the admin panel is not promised to run without its session secret', async ({ + page, + }) => { + await page.goto(DOCKER) + + const compose = requirements(page).filter({ hasText: 'default Docker Compose file' }) + await expect(compose).toContainText('ADMIN_PANEL_SESSION_SECRET') + await expect(compose.getByRole('link', { name: 'Admin Panel' })).toHaveAttribute( + 'href', + '/docs/features/admin_panel', + ) + }) + + test('@scenario:npm-guide-links-to-system-requirements an npm reader is pointed at the requirements section', async ({ + page, + }) => { + await page.goto('/docs/local/npm') + + const link = body(page).getByRole('link', { name: 'System Requirements' }) + await expect(link).toHaveAttribute('href', `${DOCKER}#system-requirements`) + + await link.click() + await expect(page).toHaveURL(new RegExp(`${DOCKER}#system-requirements$`)) + await expect(page.locator('#system-requirements')).toBeVisible() + }) +}) From 6eeed8af6c11a4f7ca38beaf6374fd562ae4d419 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Sun, 18 Oct 2026 14:48:57 +0200 Subject: [PATCH 4/4] docs: scope Docker Desktop requirements and note the source build memory --- content/docs/local/docker.mdx | 4 +- content/docs/local/npm.mdx | 3 +- e2e/local-system-requirements.spec.ts | 69 +++++++++++++++++++++------ 3 files changed, 59 insertions(+), 17 deletions(-) diff --git a/content/docs/local/docker.mdx b/content/docs/local/docker.mdx index 893e0153f..164bb6267 100644 --- a/content/docs/local/docker.mdx +++ b/content/docs/local/docker.mdx @@ -17,9 +17,9 @@ Docker Desktop is recommended for most users. For remote server installations, s LibreChat does not run AI models itself; it sends requests to the providers you configure, so it does not need a GPU. -Your computer must first meet Docker Desktop's own requirements. At the time of writing, Docker Desktop needs at least 4 GB of system RAM on [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) and [Linux](https://docs.docker.com/desktop/setup/install/linux/), and 8 GB on [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), plus hardware virtualization. Check the linked pages for the current requirements. +LibreChat's containers need at least 1 GiB of RAM and 1 vCPU, the same [minimum](/docs/remote#minimum-requirements) as on a server. The default Docker Compose file starts MongoDB, Meilisearch (conversation search), and the RAG API with a PostgreSQL/pgvector database (file search) alongside LibreChat. It also defines the admin panel, which only starts once `ADMIN_PANEL_SESSION_SECRET` is set in `.env` (see [Admin Panel](/docs/features/admin_panel)). With everything running, make at least 2 GB of memory available to Docker for smoother operation. -On top of that, LibreChat's containers need at least 1 GiB of RAM and 1 vCPU, the same [minimum](/docs/remote#minimum-requirements) as on a server. The default Docker Compose file starts MongoDB, Meilisearch (conversation search), and the RAG API with a PostgreSQL/pgvector database (file search) alongside LibreChat. It also defines the admin panel, which only starts once `ADMIN_PANEL_SESSION_SECRET` is set in `.env` (see [Admin Panel](/docs/features/admin_panel)). With everything running, give Docker at least 2 GB of memory for smoother operation. On Docker Desktop, check the memory limit under **Settings > Resources**. +If you use Docker Desktop, it runs containers inside its own virtual machine, so your computer also has to meet Docker Desktop's requirements. At the time of writing, those are at least 4 GB of system RAM on [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) and [Linux](https://docs.docker.com/desktop/setup/install/linux/), and 8 GB on [Windows](https://docs.docker.com/desktop/setup/install/windows-install/), plus hardware virtualization. Check the linked pages for the current requirements. The memory available to containers is set in Docker Desktop's [resource settings](https://docs.docker.com/desktop/settings-and-maintenance/settings/) on macOS, Linux, and Windows with Hyper-V; with the Windows WSL 2 backend, it is set on the WSL 2 virtual machine instead (see [Docker's WSL guidance](https://docs.docker.com/desktop/features/wsl/best-practices/)). Docker Engine installed directly on Linux runs containers on the host and has no separate virtual machine. 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. diff --git a/content/docs/local/npm.mdx b/content/docs/local/npm.mdx index 9c0914371..c872b2502 100644 --- a/content/docs/local/npm.mdx +++ b/content/docs/local/npm.mdx @@ -16,7 +16,8 @@ For most scenarios, Docker Compose is the recommended installation method due to - MongoDB (Atlas or Community Server) - [MongoDB Atlas](/docs/configuration/mongodb/mongodb_atlas) - [MongoDB Community Server](/docs/configuration/mongodb/mongodb_community) -- At least 1 GiB RAM and 1 vCPU. See [System Requirements](/docs/local/docker#system-requirements) for what to plan for when you add more services or run models locally. +- At least 1 GiB RAM and 1 vCPU to run LibreChat. See [System Requirements](/docs/local/docker#system-requirements) for what to plan for when you add more services or run models locally. + - Building the frontend from source (`npm run frontend`, which `npm run reinstall` also runs) needs much more memory than running it: the client build allows Node.js up to 8 GB of heap. On a low-memory machine, use the prebuilt [Docker](/docs/local/docker) images instead. If you use `nvm`, install and select the recommended Node.js version, then update npm: diff --git a/e2e/local-system-requirements.spec.ts b/e2e/local-system-requirements.spec.ts index a9a431821..d219bdad1 100644 --- a/e2e/local-system-requirements.spec.ts +++ b/e2e/local-system-requirements.spec.ts @@ -1,6 +1,7 @@ import { expect, test, type Page } from '@playwright/test' const DOCKER = '/docs/local/docker' +const NPM = '/docs/local/npm' function body(page: Page) { return page.locator('#nd-page') @@ -10,8 +11,12 @@ function requirements(page: Page) { return body(page).locator('h3#system-requirements ~ p') } +function desktop(page: Page) { + return requirements(page).filter({ hasText: 'If you use Docker Desktop' }) +} + test.describe('Local installation system requirements', () => { - test('@scenario:docker-guide-separates-host-and-container-requirements a Docker reader sees Docker Desktop host minimums apart from the container minimum', async ({ + test('@scenario:docker-guide-scopes-host-requirements-to-docker-desktop a Docker reader sees the container minimum, with host minimums only for Docker Desktop', async ({ page, }) => { await page.goto(DOCKER) @@ -20,29 +25,48 @@ test.describe('Local installation system requirements', () => { body(page).getByRole('heading', { level: 3, name: 'System Requirements' }), ).toBeVisible() - // Docker Desktop's own host requirement comes first, per platform, so the - // 1 GiB container minimum is never read as the whole machine's requirement. + const containers = requirements(page).filter({ hasText: '1 GiB of RAM and 1 vCPU' }) + await expect(containers).toHaveCount(1) + await expect(containers.getByRole('link', { name: 'minimum', exact: true })).toHaveAttribute( + 'href', + '/docs/remote#minimum-requirements', + ) + + // The Docker Desktop host minimums are conditional, so a native Docker + // Engine install on Linux is not ruled out by them. + await expect(desktop(page)).toHaveCount(1) + await expect(desktop(page)).toContainText('at least 4 GB of system RAM') + await expect(desktop(page)).toContainText('Docker Engine installed directly on Linux') for (const [name, href] of [ ['macOS', 'https://docs.docker.com/desktop/setup/install/mac-install/'], ['Linux', 'https://docs.docker.com/desktop/setup/install/linux/'], ['Windows', 'https://docs.docker.com/desktop/setup/install/windows-install/'], ]) { - await expect( - requirements(page).getByRole('link', { name, exact: true }).first(), - ).toHaveAttribute('href', href) + await expect(desktop(page).getByRole('link', { name, exact: true })).toHaveAttribute( + 'href', + href, + ) } - await expect(requirements(page).filter({ hasText: 'at least 4 GB of system RAM' })).toHaveCount( - 1, - ) - await expect(requirements(page).filter({ hasText: '1 GiB of RAM and 1 vCPU' })).toHaveCount(1) - - const minimum = requirements(page).getByRole('link', { name: 'minimum', exact: true }) - await expect(minimum).toHaveAttribute('href', '/docs/remote#minimum-requirements') await page.goto('/docs/remote') await expect(page.locator('#minimum-requirements')).toBeVisible() }) + test('@scenario:docker-guide-memory-setting-matches-desktop-backend Hyper-V and WSL 2 readers are each sent to the control that sets container memory', async ({ + page, + }) => { + await page.goto(DOCKER) + + await expect(desktop(page).getByRole('link', { name: 'resource settings' })).toHaveAttribute( + 'href', + 'https://docs.docker.com/desktop/settings-and-maintenance/settings/', + ) + await expect(desktop(page)).toContainText('with the Windows WSL 2 backend') + await expect( + desktop(page).getByRole('link', { name: "Docker's WSL guidance" }), + ).toHaveAttribute('href', 'https://docs.docker.com/desktop/features/wsl/best-practices/') + }) + test('@scenario:docker-guide-admin-panel-needs-session-secret the admin panel is not promised to run without its session secret', async ({ page, }) => { @@ -59,7 +83,7 @@ test.describe('Local installation system requirements', () => { test('@scenario:npm-guide-links-to-system-requirements an npm reader is pointed at the requirements section', async ({ page, }) => { - await page.goto('/docs/local/npm') + await page.goto(NPM) const link = body(page).getByRole('link', { name: 'System Requirements' }) await expect(link).toHaveAttribute('href', `${DOCKER}#system-requirements`) @@ -68,4 +92,21 @@ test.describe('Local installation system requirements', () => { await expect(page).toHaveURL(new RegExp(`${DOCKER}#system-requirements$`)) await expect(page.locator('#system-requirements')).toBeVisible() }) + + test('@scenario:npm-guide-warns-source-build-needs-more-memory an npm reader learns the frontend build needs more memory than the runtime minimum', async ({ + page, + }) => { + await page.goto(NPM) + + const build = body(page) + .locator('li') + .filter({ hasText: 'Building the frontend from source' }) + .last() + await expect(build).toContainText('npm run reinstall') + await expect(build).toContainText('8 GB of heap') + await expect(build.getByRole('link', { name: 'Docker', exact: true })).toHaveAttribute( + 'href', + DOCKER, + ) + }) })