diff --git a/content/docs/local/docker.mdx b/content/docs/local/docker.mdx index 48282d86e..164bb6267 100644 --- a/content/docs/local/docker.mdx +++ b/content/docs/local/docker.mdx @@ -13,6 +13,16 @@ 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. + +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. + +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. + 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..c872b2502 100644 --- a/content/docs/local/npm.mdx +++ b/content/docs/local/npm.mdx @@ -16,6 +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 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 new file mode 100644 index 000000000..d219bdad1 --- /dev/null +++ b/e2e/local-system-requirements.spec.ts @@ -0,0 +1,112 @@ +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') +} + +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-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) + + await expect( + body(page).getByRole('heading', { level: 3, name: 'System Requirements' }), + ).toBeVisible() + + 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(desktop(page).getByRole('link', { name, exact: true })).toHaveAttribute( + 'href', + href, + ) + } + + 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, + }) => { + 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(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() + }) + + 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, + ) + }) +})