diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 102b8c6d6..6f7b8f717 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -16,6 +16,6 @@ For an instance of your own, install LibreChat with the [Quick Start](/docs/quic -LibreChat is a self-hosted web application, not a native Windows app or Linux AppImage. On Windows, use [Docker Desktop](/docs/local/docker) for the simplest local setup. For Linux desktops or servers, use [Docker](/docs/local/docker), [npm](/docs/local/npm), or a [remote hosting guide](/docs/remote). +LibreChat is a self-hosted web application, not a native Windows, macOS, or Linux desktop app. On Windows, use [Docker Desktop](/docs/local/docker) for the simplest local setup. On macOS, also use [Docker Desktop](/docs/local/docker); on Apple Silicon (M-series) Macs, read the Apple Silicon MongoDB note in the Docker guide prerequisites before starting. For Linux desktops or servers, use [Docker](/docs/local/docker), [npm](/docs/local/npm), or a [remote hosting guide](/docs/remote). diff --git a/content/docs/quick_start/local_setup.mdx b/content/docs/quick_start/local_setup.mdx index 448393349..a754a6ade 100644 --- a/content/docs/quick_start/local_setup.mdx +++ b/content/docs/quick_start/local_setup.mdx @@ -37,20 +37,30 @@ git clone https://github.com/LibreChat-AI/LibreChat.git ## Step 3. Run the App -1. **Navigate to the Project Directory** +1. **Navigate to the Project Directory**: Open a terminal in the `LibreChat` folder you cloned or extracted in Step 1. If you used Git: -2. **Create and Configure .env File**: - - Copy the contents of `.env.example` to a new file named `.env`. - - Fill in any necessary values. - - For an in-depth environment configuration, see the [.env File Configuration Guide](/docs/configuration/dotenv). + ```bash + cd LibreChat + ``` -3. **Start the Application**: - - Run the following command: +2. **Create the .env File**: Copy `.env.example` to a new file named `.env`: + + ```bash + cp .env.example .env + ``` + + On Windows, use `copy .env.example .env` if `cp` is not available. + + The default values work out of the box for a basic local setup. For in-depth environment configuration, see the [.env File Configuration Guide](/docs/configuration/dotenv). + +3. **Start the Application**: Make sure Docker Desktop is running, then run: ```bash docker compose up -d ``` + The first launch downloads the Docker images and may take a few minutes. Subsequent starts are much faster. If a container stops right after starting, see the [Docker guide troubleshooting section](/docs/local/docker#troubleshooting). + ## Step 4. Start Chatting LibreChat is now running, but it needs an account and a model before it can answer anything: diff --git a/e2e/quick-start-install-steps.spec.ts b/e2e/quick-start-install-steps.spec.ts new file mode 100644 index 000000000..715129c1d --- /dev/null +++ b/e2e/quick-start-install-steps.spec.ts @@ -0,0 +1,114 @@ +import { expect, test, type Page } from '@playwright/test' + +function body(page: Page) { + return page.locator('#nd-page') +} + +// The final step each locale shows on the Docker and npm cards. The hub copy is +// hand-maintained per locale, so every dictionary has to carry it. +const OPEN_AND_REGISTER: Record = { + en: 'Open localhost:3080 and register', + de: 'localhost:3080 öffnen und registrieren', + es: 'Abre localhost:3080 y regístrate', + fr: 'Ouvrez localhost:3080 et inscrivez-vous', + id: 'Buka localhost:3080 dan daftar', + it: 'Apri localhost:3080 e registrati', + ja: 'localhost:3080 を開いてアカウント登録', + ko: 'localhost:3080을 열고 계정 등록', + nl: 'Open localhost:3080 en registreer', + pl: 'Otwórz localhost:3080 i zarejestruj się', + 'pt-BR': 'Abra localhost:3080 e cadastre-se', + tr: 'localhost:3080 adresini açın ve kaydolun', + vi: 'Mở localhost:3080 và đăng ký', + zh: '打开 localhost:3080 并注册', +} + +async function cardSteps(page: Page, method: string) { + // Each item is a number badge followed by the step label; read the label only. + return page + .getByRole('list', { name: `${method} steps` }) + .getByRole('listitem') + .locator('span:last-child') + .allInnerTexts() +} + +test.describe('Quick Start install steps', () => { + test('@scenario:quick-start-cards-end-at-first-login the Docker and npm cards end with opening LibreChat and registering', async ({ + page, + }) => { + await page.goto('/docs/quick_start') + + for (const method of ['Docker', 'npm']) { + const steps = await cardSteps(page, method) + expect(steps).toHaveLength(4) + expect(steps[3].trim()).toBe(OPEN_AND_REGISTER.en) + } + + // The npm card must match the Node.js version the npm guide pins. + await expect(body(page).getByText('Node.js v24.16.0', { exact: true })).toBeVisible() + await expect(body(page).getByText('Node.js v20.19+')).toHaveCount(0) + }) + + test('@scenario:quick-start-cards-localized-in-every-locale every locale shows the first-login step and the current Node.js version', async ({ + page, + }) => { + for (const [locale, step] of Object.entries(OPEN_AND_REGISTER)) { + if (locale === 'en') continue + await page.goto(`/${locale}/docs/quick_start`) + for (const method of ['Docker', 'npm']) { + const steps = await cardSteps(page, method) + expect(steps, `${locale} ${method}`).toHaveLength(4) + expect(steps[3].trim(), `${locale} ${method}`).toBe(step) + } + await expect(body(page).getByText('Node.js v24.16.0', { exact: true })).toBeVisible() + } + }) + + test('@scenario:local-setup-gives-exact-run-commands the Local Setup guide gives the commands to run, in order', async ({ + page, + }) => { + await page.goto('/docs/quick_start/local_setup') + + const commands = (await body(page).locator('pre').allInnerTexts()).map((text) => text.trim()) + const expected = ['cd LibreChat', 'cp .env.example .env', 'docker compose up -d'] + const positions = expected.map((command) => commands.indexOf(command)) + expect( + positions.every((position) => position >= 0), + commands.join(' | '), + ).toBe(true) + expect([...positions].sort((a, b) => a - b)).toEqual(positions) + + await expect(body(page).getByText('copy .env.example .env')).toBeVisible() + + // Step 4 still hands the reader to the first-chat walkthrough. Checked + // before leaving the page: the Docker guide links there too. Exact match + // skips the footer's next-page card, which exists regardless of Step 4. + await expect( + body(page).getByRole('link', { name: 'Your First Chat', exact: true }), + ).toHaveAttribute('href', '/docs/quick_start/first_chat') + + // The failure path points somewhere that exists. + const troubleshooting = body(page).getByRole('link', { + name: 'Docker guide troubleshooting section', + }) + await expect(troubleshooting).toHaveAttribute('href', '/docs/local/docker#troubleshooting') + await troubleshooting.click() + await expect(page).toHaveURL(/\/docs\/local\/docker#troubleshooting$/) + await expect(page.locator('#troubleshooting')).toBeVisible() + }) + + test('@scenario:docs-landing-desktop-callout-covers-macos the desktop installer callout tells Mac readers what to use', async ({ + page, + }) => { + await page.goto('/docs') + + const callout = body(page).getByText('Looking for a desktop installer?').locator('..') + await expect(callout).toContainText('On macOS, also use Docker Desktop') + await expect(callout).toContainText('Apple Silicon (M-series)') + const dockerLinks = callout.getByRole('link', { name: 'Docker Desktop' }) + await expect(dockerLinks).toHaveCount(2) + for (const link of await dockerLinks.all()) { + await expect(link).toHaveAttribute('href', '/docs/local/docker') + } + }) +}) diff --git a/lib/ui-i18n.ts b/lib/ui-i18n.ts index 77b9806f8..44a0141d1 100644 --- a/lib/ui-i18n.ts +++ b/lib/ui-i18n.ts @@ -126,7 +126,12 @@ const en = { tag: 'Recommended', time: '~5 min', description: 'Everything included — MongoDB, MeiliSearch, and RAG API run automatically.', - steps: ['Clone the repository', 'Copy .env.example to .env', 'Run docker compose up'], + steps: [ + 'Clone the repository', + 'Copy .env.example to .env', + 'Run docker compose up', + 'Open localhost:3080 and register', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -138,8 +143,9 @@ const en = { 'Clone and install dependencies', 'Configure .env and start MongoDB', 'Run npm run backend', + 'Open localhost:3080 and register', ], - prereqs: ['Node.js v20.19+', 'MongoDB instance'], + prereqs: ['Node.js v24.16.0', 'MongoDB instance'], }, railway: { tag: 'One-click', diff --git a/lib/ui-translations/de.ts b/lib/ui-translations/de.ts index 2302c1966..414504d6f 100644 --- a/lib/ui-translations/de.ts +++ b/lib/ui-translations/de.ts @@ -103,6 +103,7 @@ export const de: UIStrings = { 'Repository klonen', '.env.example nach .env kopieren', 'docker compose up ausführen', + 'localhost:3080 öffnen und registrieren', ], prereqs: ['Docker Desktop'], }, @@ -115,8 +116,9 @@ export const de: UIStrings = { 'Klonen und Abhängigkeiten installieren', '.env konfigurieren und MongoDB starten', 'npm run backend ausführen', + 'localhost:3080 öffnen und registrieren', ], - prereqs: ['Node.js v20.19+', 'MongoDB-Instanz'], + prereqs: ['Node.js v24.16.0', 'MongoDB-Instanz'], }, railway: { tag: 'Ein-Klick', diff --git a/lib/ui-translations/es.ts b/lib/ui-translations/es.ts index de4c7458d..63172340a 100644 --- a/lib/ui-translations/es.ts +++ b/lib/ui-translations/es.ts @@ -106,6 +106,7 @@ export const es: UIStrings = { 'Clonar el repositorio', 'Copiar .env.example a .env', 'Ejecutar docker compose up', + 'Abre localhost:3080 y regístrate', ], prereqs: ['Docker Desktop'], }, @@ -118,8 +119,9 @@ export const es: UIStrings = { 'Clonar e instalar dependencias', 'Configurar .env e iniciar MongoDB', 'Ejecutar npm run backend', + 'Abre localhost:3080 y regístrate', ], - prereqs: ['Node.js v20.19+', 'Instancia de MongoDB'], + prereqs: ['Node.js v24.16.0', 'Instancia de MongoDB'], }, railway: { tag: 'Un clic', diff --git a/lib/ui-translations/fr.ts b/lib/ui-translations/fr.ts index 628b130a8..2eae4e8a1 100644 --- a/lib/ui-translations/fr.ts +++ b/lib/ui-translations/fr.ts @@ -103,7 +103,12 @@ export const fr: UIStrings = { time: '~5 min', description: "Tout est inclus — MongoDB, MeiliSearch et RAG API s'exécutent automatiquement.", - steps: ['Cloner le dépôt', 'Copier .env.example vers .env', 'Exécuter docker compose up'], + steps: [ + 'Cloner le dépôt', + 'Copier .env.example vers .env', + 'Exécuter docker compose up', + 'Ouvrez localhost:3080 et inscrivez-vous', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -115,8 +120,9 @@ export const fr: UIStrings = { 'Cloner et installer les dépendances', 'Configurer .env et démarrer MongoDB', 'Exécuter npm run backend', + 'Ouvrez localhost:3080 et inscrivez-vous', ], - prereqs: ['Node.js v20.19+', 'Instance MongoDB'], + prereqs: ['Node.js v24.16.0', 'Instance MongoDB'], }, railway: { tag: 'En un clic', diff --git a/lib/ui-translations/id.ts b/lib/ui-translations/id.ts index afb172530..3863e978d 100644 --- a/lib/ui-translations/id.ts +++ b/lib/ui-translations/id.ts @@ -99,7 +99,12 @@ export const id: UIStrings = { time: '~5 mnt', description: 'Semuanya sudah termasuk — MongoDB, MeiliSearch, dan RAG API berjalan otomatis.', - steps: ['Clone repository', 'Salin .env.example ke .env', 'Jalankan docker compose up'], + steps: [ + 'Clone repository', + 'Salin .env.example ke .env', + 'Jalankan docker compose up', + 'Buka localhost:3080 dan daftar', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -111,8 +116,9 @@ export const id: UIStrings = { 'Clone dan instal dependensi', 'Konfigurasikan .env dan mulai MongoDB', 'Jalankan npm run backend', + 'Buka localhost:3080 dan daftar', ], - prereqs: ['Node.js v20.19+', 'Instance MongoDB'], + prereqs: ['Node.js v24.16.0', 'Instance MongoDB'], }, railway: { tag: 'Sekali klik', diff --git a/lib/ui-translations/it.ts b/lib/ui-translations/it.ts index e867e3c7c..a8a6e75dd 100644 --- a/lib/ui-translations/it.ts +++ b/lib/ui-translations/it.ts @@ -99,7 +99,12 @@ export const it: UIStrings = { time: '~5 min', description: 'Tutto incluso — MongoDB, MeiliSearch e RAG API vengono eseguiti automaticamente.', - steps: ['Clona il repository', 'Copia .env.example in .env', 'Esegui docker compose up'], + steps: [ + 'Clona il repository', + 'Copia .env.example in .env', + 'Esegui docker compose up', + 'Apri localhost:3080 e registrati', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -111,8 +116,9 @@ export const it: UIStrings = { 'Clona e installa le dipendenze', 'Configura .env e avvia MongoDB', 'Esegui npm run backend', + 'Apri localhost:3080 e registrati', ], - prereqs: ['Node.js v20.19+', 'Istanza MongoDB'], + prereqs: ['Node.js v24.16.0', 'Istanza MongoDB'], }, railway: { tag: 'Un clic', diff --git a/lib/ui-translations/ja.ts b/lib/ui-translations/ja.ts index 5e9a1308e..3659a2edd 100644 --- a/lib/ui-translations/ja.ts +++ b/lib/ui-translations/ja.ts @@ -106,6 +106,7 @@ export const ja: UIStrings = { 'リポジトリをクローン', '.env.example を .env にコピー', 'docker compose up を実行', + 'localhost:3080 を開いてアカウント登録', ], prereqs: ['Docker Desktop'], }, @@ -118,8 +119,9 @@ export const ja: UIStrings = { 'クローンして依存関係をインストール', '.env を設定し MongoDB を起動', 'npm run backend を実行', + 'localhost:3080 を開いてアカウント登録', ], - prereqs: ['Node.js v20.19+', 'MongoDB インスタンス'], + prereqs: ['Node.js v24.16.0', 'MongoDB インスタンス'], }, railway: { tag: 'ワンクリック', diff --git a/lib/ui-translations/ko.ts b/lib/ui-translations/ko.ts index b9c8e350d..ba6b320fb 100644 --- a/lib/ui-translations/ko.ts +++ b/lib/ui-translations/ko.ts @@ -99,7 +99,12 @@ export const ko: UIStrings = { time: '~5분', description: '모든 것이 포함되어 있습니다 — MongoDB, MeiliSearch, RAG API가 자동으로 실행됩니다.', - steps: ['저장소 복제', '.env.example을 .env로 복사', 'docker compose up 실행'], + steps: [ + '저장소 복제', + '.env.example을 .env로 복사', + 'docker compose up 실행', + 'localhost:3080을 열고 계정 등록', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -107,8 +112,13 @@ export const ko: UIStrings = { time: '~20분', description: 'Node.js를 사용한 수동 설정입니다. 별도의 MongoDB 및 MeiliSearch 인스턴스가 필요합니다.', - steps: ['복제하고 의존성 설치', '.env 구성 및 MongoDB 시작', 'npm run backend 실행'], - prereqs: ['Node.js v20.19+', 'MongoDB 인스턴스'], + steps: [ + '복제하고 의존성 설치', + '.env 구성 및 MongoDB 시작', + 'npm run backend 실행', + 'localhost:3080을 열고 계정 등록', + ], + prereqs: ['Node.js v24.16.0', 'MongoDB 인스턴스'], }, railway: { tag: '원클릭', diff --git a/lib/ui-translations/nl.ts b/lib/ui-translations/nl.ts index af55c21bc..b9fac1da9 100644 --- a/lib/ui-translations/nl.ts +++ b/lib/ui-translations/nl.ts @@ -102,6 +102,7 @@ export const nl: UIStrings = { 'Clone de repository', 'Kopieer .env.example naar .env', 'Voer docker compose up uit', + 'Open localhost:3080 en registreer', ], prereqs: ['Docker Desktop'], }, @@ -114,8 +115,9 @@ export const nl: UIStrings = { 'Clone en installeer afhankelijkheden', 'Configureer .env en start MongoDB', 'Voer npm run backend uit', + 'Open localhost:3080 en registreer', ], - prereqs: ['Node.js v20.19+', 'MongoDB-instantie'], + prereqs: ['Node.js v24.16.0', 'MongoDB-instantie'], }, railway: { tag: 'Eén klik', diff --git a/lib/ui-translations/pl.ts b/lib/ui-translations/pl.ts index cd3d9cd93..60d166771 100644 --- a/lib/ui-translations/pl.ts +++ b/lib/ui-translations/pl.ts @@ -103,6 +103,7 @@ export const pl: UIStrings = { 'Sklonuj repozytorium', 'Skopiuj .env.example do .env', 'Uruchom docker compose up', + 'Otwórz localhost:3080 i zarejestruj się', ], prereqs: ['Docker Desktop'], }, @@ -115,8 +116,9 @@ export const pl: UIStrings = { 'Sklonuj i zainstaluj zależności', 'Skonfiguruj .env i uruchom MongoDB', 'Uruchom npm run backend', + 'Otwórz localhost:3080 i zarejestruj się', ], - prereqs: ['Node.js v20.19+', 'Instancja MongoDB'], + prereqs: ['Node.js v24.16.0', 'Instancja MongoDB'], }, railway: { tag: 'Jedno kliknięcie', diff --git a/lib/ui-translations/pt-BR.ts b/lib/ui-translations/pt-BR.ts index e79b07232..059febab0 100644 --- a/lib/ui-translations/pt-BR.ts +++ b/lib/ui-translations/pt-BR.ts @@ -99,7 +99,12 @@ export const ptBR: UIStrings = { time: '~5 min', description: 'Tudo incluído — MongoDB, MeiliSearch e RAG API são executados automaticamente.', - steps: ['Clone o repositório', 'Copie .env.example para .env', 'Execute docker compose up'], + steps: [ + 'Clone o repositório', + 'Copie .env.example para .env', + 'Execute docker compose up', + 'Abra localhost:3080 e cadastre-se', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -111,8 +116,9 @@ export const ptBR: UIStrings = { 'Clone e instale as dependências', 'Configure .env e inicie o MongoDB', 'Execute npm run backend', + 'Abra localhost:3080 e cadastre-se', ], - prereqs: ['Node.js v20.19+', 'Instância MongoDB'], + prereqs: ['Node.js v24.16.0', 'Instância MongoDB'], }, railway: { tag: 'Um clique', diff --git a/lib/ui-translations/tr.ts b/lib/ui-translations/tr.ts index 38e77f13e..f38edb7d2 100644 --- a/lib/ui-translations/tr.ts +++ b/lib/ui-translations/tr.ts @@ -102,6 +102,7 @@ export const tr: UIStrings = { "Repository'yi klonla", ".env.example'ı .env olarak kopyala", 'docker compose up çalıştır', + 'localhost:3080 adresini açın ve kaydolun', ], prereqs: ['Docker Desktop'], }, @@ -113,8 +114,9 @@ export const tr: UIStrings = { 'Klonla ve bağımlılıkları yükle', ".env'yi yapılandır ve MongoDB'yi başlat", 'npm run backend çalıştır', + 'localhost:3080 adresini açın ve kaydolun', ], - prereqs: ['Node.js v20.19+', 'MongoDB örneği'], + prereqs: ['Node.js v24.16.0', 'MongoDB örneği'], }, railway: { tag: 'Tek tık', diff --git a/lib/ui-translations/vi.ts b/lib/ui-translations/vi.ts index 672083d98..50663b456 100644 --- a/lib/ui-translations/vi.ts +++ b/lib/ui-translations/vi.ts @@ -98,7 +98,12 @@ export const vi: UIStrings = { tag: 'Được khuyến nghị', time: '~5 phút', description: 'Đã bao gồm mọi thứ — MongoDB, MeiliSearch và RAG API tự động chạy.', - steps: ['Clone repository', 'Sao chép .env.example thành .env', 'Chạy docker compose up'], + steps: [ + 'Clone repository', + 'Sao chép .env.example thành .env', + 'Chạy docker compose up', + 'Mở localhost:3080 và đăng ký', + ], prereqs: ['Docker Desktop'], }, npm: { @@ -110,8 +115,9 @@ export const vi: UIStrings = { 'Clone và cài đặt dependency', 'Cấu hình .env và khởi động MongoDB', 'Chạy npm run backend', + 'Mở localhost:3080 và đăng ký', ], - prereqs: ['Node.js v20.19+', 'Phiên bản MongoDB'], + prereqs: ['Node.js v24.16.0', 'Phiên bản MongoDB'], }, railway: { tag: 'Một cú nhấp', diff --git a/lib/ui-translations/zh.ts b/lib/ui-translations/zh.ts index 56192a268..c29956422 100644 --- a/lib/ui-translations/zh.ts +++ b/lib/ui-translations/zh.ts @@ -96,15 +96,25 @@ export const zh: UIStrings = { tag: '推荐', time: '约 5 分钟', description: '一切尽在其中——MongoDB、MeiliSearch 和 RAG API 自动运行。', - steps: ['克隆仓库', '将 .env.example 复制为 .env', '运行 docker compose up'], + steps: [ + '克隆仓库', + '将 .env.example 复制为 .env', + '运行 docker compose up', + '打开 localhost:3080 并注册', + ], prereqs: ['Docker Desktop'], }, npm: { tag: '', time: '约 20 分钟', description: '使用 Node.js 手动部署。需要单独的 MongoDB 和 MeiliSearch 实例。', - steps: ['克隆并安装依赖', '配置 .env 并启动 MongoDB', '运行 npm run backend'], - prereqs: ['Node.js v20.19+', 'MongoDB 实例'], + steps: [ + '克隆并安装依赖', + '配置 .env 并启动 MongoDB', + '运行 npm run backend', + '打开 localhost:3080 并注册', + ], + prereqs: ['Node.js v24.16.0', 'MongoDB 实例'], }, railway: { tag: '一键部署',