Installation

LibreChat offers multiple installation methods to suit different needs, from quick Docker deployments to full local development setups. This guide covers all installation options in detail.

Docker (Recommended)

Fastest and most reliable method for production use

npm/Local Installation

Full development environment with hot reloading

Cloud Deployment

One-click deployment to cloud platforms

System Requirements

Minimum Requirements

CPU: 2 cores
RAM: 2GB minimum, 4GB recommended
Storage: 10GB free disk space
OS: Linux, macOS, or Windows (with WSL2 for Docker)

Software Requirements

Docker Installation
Local Installation

Docker Engine 20.10+
Docker Compose v2.0+

LibreChat uses the packageManager field in package.json to specify npm@11.10.0. Modern Node.js installations will automatically use the correct version.

Docker Installation (Recommended)

Docker is the recommended installation method for most users. It provides isolation, easy updates, and consistent environments.

Standard Docker Setup

Install Docker

Install Docker Desktop or Docker Engine on your system:

# Update package index
sudo apt update

# Install Docker
sudo apt install docker.io docker-compose-plugin

# Start Docker service
sudo systemctl enable --now docker

# Add your user to docker group (logout/login required)
sudo usermod -aG docker $USER

Verify installation:

docker --version
docker compose version

Clone Repository

git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

Configure Environment

Create and configure your .env file:

cp .env.example .env

Edit .env with your preferred editor. Required configuration:

.env

# Server Configuration
HOST=localhost
PORT=3080
MONGO_URI=mongodb://mongodb:27017/LibreChat

# Domain Configuration
DOMAIN_CLIENT=http://localhost:3080
DOMAIN_SERVER=http://localhost:3080

# Meilisearch (for conversation search)
MEILI_HOST=http://meilisearch:7700
MEILI_MASTER_KEY=DrhYf7zENyR6AlUCKmnz0eYASOQdl6zxH7s7MKFSfFCt

# Security Keys (generate new ones for production!)
JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418
CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb

# AI Provider API Keys (at least one required)
OPENAI_API_KEY=user_provided
ANTHROPIC_API_KEY=user_provided
GOOGLE_KEY=user_provided

# Registration Settings
ALLOW_REGISTRATION=true
ALLOW_EMAIL_LOGIN=true
ALLOW_UNVERIFIED_EMAIL_LOGIN=true

Security: The example security keys are for development only. Generate new random keys for production:

# Generate secure random keys
openssl rand -hex 32  # For JWT_SECRET
openssl rand -hex 32  # For JWT_REFRESH_SECRET
openssl rand -hex 32  # For CREDS_KEY
openssl rand -hex 16  # For CREDS_IV
openssl rand -hex 32  # For MEILI_MASTER_KEY

Set File Permissions

Configure user and group IDs for proper file permissions:

# Linux/macOS: Add to .env
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env

# Windows WSL2: Use default
echo "UID=1000" >> .env
echo "GID=1000" >> .env

Start Services

Launch all containers:

docker compose up -d

This starts:

LibreChat (api) - Main application
MongoDB - Database
Meilisearch - Search engine
RAG API - Document processing (optional)
VectorDB - PostgreSQL with pgvector

Monitor startup:

# Watch logs
docker compose logs -f api

# Check service status
docker compose ps

Access LibreChat

Open your browser to:

http://localhost:3080

Create your first account to get started.

Docker Compose Configuration

The default docker-compose.yml includes all services. Here’s what each service does:

docker-compose.yml

services:
  api:
    container_name: LibreChat
    image: registry.librechat.ai/danny-avila/librechat-dev:latest
    ports:
      - "${PORT}:${PORT}"
    depends_on:
      - mongodb
      - rag_api
    environment:
      - HOST=0.0.0.0
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
      - MEILI_HOST=http://meilisearch:7700
      - RAG_API_URL=http://rag_api:8000
    volumes:
      - ./.env:/app/.env
      - ./uploads:/app/uploads
      - ./logs:/app/logs

  mongodb:
    image: mongo:8.0.17
    volumes:
      - ./data-node:/data/db

  meilisearch:
    image: getmeili/meilisearch:v1.35.1
    environment:
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
    volumes:
      - ./meili_data_v1.35.1:/meili_data

  vectordb:
    image: pgvector/pgvector:0.8.0-pg15-trixie
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    volumes:
      - pgdata2:/var/lib/postgresql/data

  rag_api:
    image: registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest
    environment:
      - DB_HOST=vectordb
    depends_on:
      - vectordb

Customizing Docker Deployment

Create a docker-compose.override.yml file for customizations (see docker-compose.override.yml.example):

docker-compose.override.yml

services:
  api:
    # Use a specific version
    image: registry.librechat.ai/danny-avila/librechat:v0.8.3
    
    # Add custom ports
    ports:
      - "3080:3080"
    
    # Mount additional volumes
    volumes:
      - ./custom-config:/app/config
    
    # Override environment variables
    environment:
      - DEBUG_LOGGING=true
      - NODE_OPTIONS=--max-old-space-size=4096

  mongodb:
    # Enable authentication
    command: mongod --auth
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: secure_password

Local/npm Installation

Install LibreChat directly on your system for development or when Docker isn’t suitable.

Install Prerequisites

Ubuntu/Debian
macOS
Windows

# Install Node.js 20.x
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install MongoDB
wget -qO - https://www.mongodb.org/static/pgp/server-8.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu $(lsb_release -cs)/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt update
sudo apt install -y mongodb-org

# Start MongoDB
sudo systemctl enable --now mongod

# Install Meilisearch
curl -L https://install.meilisearch.com | sh

# Install Node.js
brew install node@20

# Install MongoDB
brew tap mongodb/brew
brew install mongodb-community@8.0
brew services start mongodb-community@8.0

# Install Meilisearch
brew install meilisearch
brew services start meilisearch

# Install Node.js from https://nodejs.org/
# Install MongoDB from https://www.mongodb.com/try/download/community
# Install Meilisearch from https://www.meilisearch.com/docs/learn/getting_started/installation

# Or use Chocolatey:
choco install nodejs mongodb meilisearch

Verify installations:

node --version  # Should be v20.19.0+
npm --version   # Should be 11.10.0+
mongod --version

Clone and Configure

# Clone repository
git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

# Create environment file
cp .env.example .env

Edit .env for local setup:

.env

# Use local MongoDB
MONGO_URI=mongodb://127.0.0.1:27017/LibreChat

# Local Meilisearch
MEILI_HOST=http://127.0.0.1:7700
MEILI_MASTER_KEY=your_secure_master_key

# Server configuration
HOST=localhost
PORT=3080
DOMAIN_CLIENT=http://localhost:3080
DOMAIN_SERVER=http://localhost:3080

# Add your AI provider keys
OPENAI_API_KEY=sk-your-key-here

Install Dependencies

LibreChat uses npm workspaces. Install all dependencies:

# Smart install (only if package-lock.json changed)
npm run smart-reinstall

# Or full clean install
npm run reinstall

This installs dependencies for:

Root workspace
/api - Backend server
/client - Frontend React app
/packages/* - Shared libraries

Build the Application

# Build all packages (uses Turborepo for speed)
npm run build

This compiles:

packages/data-provider - Shared API types
packages/data-schemas - Database schemas
packages/api - TypeScript backend code
packages/client - Frontend utilities
client - React frontend build

Start Meilisearch

In a separate terminal:

# Linux/macOS
meilisearch --master-key="your_secure_master_key" --db-path ./meili_data

# Or run as background service
meilisearch --master-key="your_secure_master_key" --db-path ./meili_data &

Start the Backend

In the main terminal:

# Production mode
npm run backend

# Development mode (with file watching)
npm run backend:dev

The backend runs on http://localhost:3080

Start the Frontend (Development)

For development with hot module reloading, in another terminal:

npm run frontend:dev

The dev server runs on http://localhost:3090 and proxies API requests to :3080

Access LibreChat

Production build: http://localhost:3080
Development: http://localhost:3090

Create your account and start chatting!

Development Commands

Common commands for local development:

# Install/Update dependencies
npm run smart-reinstall      # Install only if lockfile changed
npm run reinstall            # Clean install from scratch

# Build commands
npm run build                # Build all packages (Turborepo)
npm run build:data-provider  # Rebuild data-provider only
npm run build:client         # Build frontend only

# Run backend
npm run backend              # Production mode
npm run backend:dev          # Development with file watching
npm run backend:inspect      # With Node.js debugger

# Run frontend
npm run frontend:dev         # Development server (port 3090)

# User management
npm run create-user          # Create a new user
npm run list-users           # List all users
npm run reset-password       # Reset user password
npm run ban-user             # Ban a user
npm run delete-user          # Delete a user

# Balance management (if CHECK_BALANCE enabled)
npm run add-balance          # Add token balance to user
npm run set-balance          # Set user token balance
npm run list-balances        # List user balances

# Testing
npm run test:api             # Run API tests
npm run test:client          # Run frontend tests
npm run test:all             # Run all tests

# Linting and formatting
npm run lint                 # Check for lint errors
npm run lint:fix             # Auto-fix lint errors
npm run format               # Format code with Prettier

Cloud Deployment

Deploy LibreChat to cloud platforms with one click:

Railway

Deploy to Railway with MongoDB and automatic HTTPS

Zeabur

Deploy to Zeabur with serverless scaling

Sealos

Deploy to Sealos cloud platform

Cloud Deployment Considerations

Before deploying to production:

Generate new security keys (don’t use example keys!)
Set up proper authentication (OAuth2, LDAP, or email verification)
Configure file storage (S3, Azure Blob, or Firebase)
Enable HTTPS (required for OAuth and security)
Set up monitoring (logs, error tracking)
Configure backups (MongoDB and uploaded files)
Review rate limits and moderation settings

Environment Variables for Production

.env

# Production domains
DOMAIN_CLIENT=https://your-domain.com
DOMAIN_SERVER=https://your-domain.com

# Disable registration after initial setup
ALLOW_REGISTRATION=false

# Require email verification
ALLOW_UNVERIFIED_EMAIL_LOGIN=false

# Enable production mode
NODE_ENV=production

# Configure reverse proxy trust
TRUST_PROXY=1

# Enable Redis for multi-instance deployments
USE_REDIS=true
REDIS_URI=redis://your-redis-host:6379

# S3 file storage
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1
AWS_BUCKET_NAME=librechat-files

# Email configuration (for password reset)
EMAIL_SERVICE=smtp
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-app-password
EMAIL_FROM=noreply@your-domain.com

# OAuth (optional but recommended)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_CALLBACK_URL=https://your-domain.com/oauth/google/callback

Updating LibreChat

Docker Update

# Stop containers
docker compose down

# Pull latest code
git pull origin main

# Pull latest images
docker compose pull

# Start with new version
docker compose up -d

Local Installation Update

# Pull latest code
git pull origin main

# Update dependencies and rebuild
npm run smart-reinstall
npm run build

# Restart backend
npm run backend

Before updating, always:

Check the changelog for breaking changes
Backup your database: docker compose exec mongodb mongodump --out /data/db/backup
Backup your .env file
Review migration notes for your version

Troubleshooting

Docker Issues

Container fails to start

# Check logs
docker compose logs api

# Common issues:
# 1. Port conflict - change PORT in .env
# 2. Invalid .env format - check for quotes/spaces
# 3. Permission errors - verify UID/GID settings

# Reset containers
docker compose down
docker compose up -d

MongoDB connection errors

# Check MongoDB is running
docker compose ps mongodb

# View MongoDB logs
docker compose logs mongodb

# Reset MongoDB (WARNING: deletes data)
docker compose down
sudo rm -rf ./data-node
docker compose up -d

File permission errors

# Fix ownership of data directories
sudo chown -R $(id -u):$(id -g) ./data-node ./meili_data_v1.35.1 ./uploads ./logs

# Ensure UID/GID are set in .env
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env

docker compose restart

Local Installation Issues

Build errors

# Clear caches and rebuild
npm run reinstall
npm run build

# If still failing, check Node.js version
node --version  # Must be v20.19.0+

# Install specific Node version with nvm:
nvm install 20
nvm use 20

MongoDB not connecting

# Check MongoDB is running
sudo systemctl status mongod

# Start MongoDB
sudo systemctl start mongod

# Check connection
mongosh mongodb://127.0.0.1:27017/LibreChat

# If connection refused, check MONGO_URI in .env

Meilisearch not working

# Start Meilisearch with correct key
meilisearch --master-key="DrhYf7zENyR6AlUCKmnz0eYASOQdl6zxH7s7MKFSfFCt" --db-path ./meili_data

# Verify it's running
curl http://127.0.0.1:7700/health

# Check MEILI_HOST and MEILI_MASTER_KEY match in .env

Next Steps

Configuration Guide

Configure AI endpoints, authentication, and advanced features

User Management

Set up user accounts, OAuth, and permissions

AI Agents

Create custom AI agents with tools and capabilities

API Reference

Integrate LibreChat with your applications

Need help? Join the Discord community for support, or check the GitHub issues for known problems and solutions.

Get Started

Core Features

Configuration

Deployment

User Management

Installation Guide

Installation

Docker (Recommended)

npm/Local Installation

Cloud Deployment

System Requirements

Minimum Requirements

Software Requirements

Docker Installation (Recommended)

Standard Docker Setup

Docker Compose Configuration

Customizing Docker Deployment

Local/npm Installation

Development Commands

Cloud Deployment

Railway

Zeabur

Sealos

Cloud Deployment Considerations

Environment Variables for Production

Updating LibreChat

Docker Update

Local Installation Update

Troubleshooting

Docker Issues

Local Installation Issues

Next Steps

Configuration Guide

User Management

AI Agents

API Reference

Get Started

Core Features

Configuration

Deployment

User Management

​Installation

Docker (Recommended)

npm/Local Installation

Cloud Deployment

​System Requirements

​Minimum Requirements

​Software Requirements

​Docker Installation (Recommended)

​Standard Docker Setup

​Docker Compose Configuration

​Customizing Docker Deployment

​Local/npm Installation

​Development Commands

​Cloud Deployment

Railway

Zeabur

Sealos

​Cloud Deployment Considerations

​Environment Variables for Production

​Updating LibreChat

​Docker Update

​Local Installation Update

​Troubleshooting

​Docker Issues

​Local Installation Issues

​Next Steps

Configuration Guide

User Management

AI Agents

API Reference

Installation

System Requirements

Minimum Requirements

Software Requirements

Docker Installation (Recommended)

Standard Docker Setup

Docker Compose Configuration

Customizing Docker Deployment

Local/npm Installation

Development Commands

Cloud Deployment

Cloud Deployment Considerations

Environment Variables for Production

Updating LibreChat

Docker Update

Local Installation Update

Troubleshooting

Docker Issues

Local Installation Issues

Next Steps