Skip to main content

​
Docker Deployment

Deploy LibreChat using Docker for a production-ready, containerized setup. This guide covers both development and production deployments.

​
Prerequisites

  • Docker Engine 20.10+
  • Docker Compose v2.0+
  • At least 4GB RAM available
  • 10GB disk space

​
Quick Start

1

Clone the Repository

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

Configure Environment

Copy the example environment file and configure your API keys:
cp .env.example .env
Edit .env and set required variables:
# Server Configuration
HOST=localhost
PORT=3080
MONGO_URI=mongodb://mongodb:27017/LibreChat

# AI Provider API Keys (set to user_provided or your key)
OPENAI_API_KEY=user_provided
ANTHROPIC_API_KEY=user_provided
GOOGLE_KEY=user_provided

# Security (generate with: openssl rand -hex 32)
CREDS_KEY=your_generated_key_here
CREDS_IV=your_generated_iv_here  # openssl rand -hex 16
JWT_SECRET=your_jwt_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here

# Search
MEILI_MASTER_KEY=your_meili_master_key

# Permissions (set your user ID and group ID)
UID=1000
GID=1000
Generate secure keys with:
openssl rand -hex 32  # for CREDS_KEY, JWT_SECRET, JWT_REFRESH_SECRET
openssl rand -hex 16  # for CREDS_IV
3

Start the Application

docker compose up -d
This starts all required services:
  • LibreChat API (port 3080)
  • MongoDB (internal)
  • Meilisearch (internal)
  • Vector Database (pgvector)
  • RAG API (internal)
4

Access LibreChat

Open your browser and navigate to:
http://localhost:3080
Create your account and start chatting!

​
Docker Compose Files

​
Development Setup (docker-compose.yml)

The default docker-compose.yml uses pre-built development images: 
services:
  api:
    container_name: LibreChat
    ports:
      - "${PORT}:${PORT}"
    depends_on:
      - mongodb
      - rag_api
    image: registry.librechat.ai/danny-avila/librechat-dev:latest
    restart: always
    user: "${UID}:${GID}"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - HOST=0.0.0.0
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
      - MEILI_HOST=http://meilisearch:7700
      - RAG_API_URL=http://rag_api:${RAG_PORT:-8000}
    volumes:
      - ./.env:/app/.env
      - ./images:/app/client/public/images
      - ./uploads:/app/uploads
      - ./logs:/app/logs

  mongodb:
    container_name: chat-mongodb
    image: mongo:8.0.17
    restart: always
    user: "${UID}:${GID}"
    volumes:
      - ./data-node:/data/db
    command: mongod --noauth

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

​
Production Setup (deploy-compose.yml)

For production deployments with separate API and NGINX: 
services:
  api:
    image: registry.librechat.ai/danny-avila/librechat-dev-api:latest
    container_name: LibreChat-API
    ports:
      - 3080:3080
    environment:
      - NODE_ENV=production
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
    volumes:
      - ./librechat.yaml:/app/librechat.yaml
      - ./uploads:/app/uploads
      - ./logs:/app/api/logs

  client:
    image: nginx:1.27.0-alpine
    container_name: LibreChat-NGINX
    ports:
      - 80:80
      - 443:443
    depends_on:
      - api
    volumes:
      - ./client/nginx.conf:/etc/nginx/conf.d/default.conf

​
Building from Source

​
Standard Dockerfile

Build using the single-stage Dockerfile:
1

Build the Image

docker build -t librechat .
With custom memory allocation:
docker build --build-arg NODE_MAX_OLD_SPACE_SIZE=8192 -t librechat .
2

Create Override File

Create docker-compose.override.yml:
services:
  api:
    image: librechat
    build:
      context: .
      target: node
3

Build and Start

docker compose build
docker compose up -d

​
Multi-Stage Dockerfile

For optimized production builds: 
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile.multi
      target: api-build
      args:
        NODE_MAX_OLD_SPACE_SIZE: 6144
Build command: 
docker compose -f deploy-compose.yml build
docker compose -f deploy-compose.yml up -d

​
Configuration Options

​
Using librechat.yaml

Mount your custom configuration: 
services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

​
Volume Persistence

Data is persisted in these locations: 
volumes:
  - ./data-node:/data/db              # MongoDB data
  - ./meili_data_v1.35.1:/meili_data  # Meilisearch index
  - ./images:/app/client/public/images # User images
  - ./uploads:/app/uploads             # File uploads
  - ./logs:/app/logs                   # Application logs

​
Environment Variables

Key environment variables for Docker deployment:
VariableDescriptionDefault
PORTApplication port3080
HOSTBind address0.0.0.0
MONGO_URIMongoDB connection stringmongodb://mongodb:27017/LibreChat
MEILI_HOSTMeilisearch endpointhttp://meilisearch:7700
RAG_API_URLRAG API endpointhttp://rag_api:8000
UIDUser ID for file permissions1000
GIDGroup ID for file permissions1000
NODE_ENVEnvironment modeproduction

​
Management Commands

​
Update LibreChat

# Using npm script
npm run update:docker

# Or manually
docker compose pull
docker compose up -d

​
View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

​
Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart api

​
Stop and Remove

# Stop services
docker compose down

# Stop and remove volumes (⚠️ deletes all data)
docker compose down -v

​
User Management

Manage users with npm scripts: 
# Create a new user
npm run create-user

# Reset password
npm run reset-password

# List all users
npm run list-users

# Ban a user
npm run ban-user

# Delete a user
npm run delete-user

​
Troubleshooting

​
Permission Issues

If you encounter permission errors: 
# Set correct UID and GID in .env
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env

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

​
MongoDB Connection Issues

Check MongoDB is running: 
docker compose logs mongodb
Test connection: 
docker exec -it chat-mongodb mongosh --eval "db.adminCommand('ping')"

​
Container Won’t Start

Check resource usage: 
docker stats
Inspect failed container: 
docker compose logs api

​
Reset Everything

# Stop all services
docker compose down -v

# Remove data directories
rm -rf data-node meili_data_v1.35.1 logs

# Start fresh
docker compose up -d

​
Advanced Configuration

​
Adding Mongo Express (Database UI)

Add to docker-compose.override.yml: 
services:
  mongo-express:
    image: mongo-express
    container_name: mongo-express
    environment:
      ME_CONFIG_MONGODB_SERVER: mongodb
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: password
    ports:
      - '8081:8081'
    depends_on:
      - mongodb
    restart: always
Access at http://localhost:8081

​
Using External MongoDB

services:
  api:
    environment:
      - MONGO_URI=mongodb://your-external-mongo:27017/LibreChat
  mongodb:
    image: tianon/true
    command: ""
    entrypoint: ""

​
Enable Redis for Caching

Add Redis service and configure LibreChat: 
services:
  redis:
    image: redis:7-alpine
    command: redis-server --requirepass your_redis_password
    volumes:
      - ./redis:/data
Update .env: 
USE_REDIS=true
REDIS_URI=redis://redis:6379
REDIS_PASSWORD=your_redis_password

​
Production Checklist

  • Generate strong secrets for CREDS_KEY, JWT_SECRET, and MEILI_MASTER_KEY
  • Change default UID and GID to match your system
  • Configure proper backup strategy for data-node and meili_data_v1.35.1
  • Set up SSL/TLS with reverse proxy (nginx, Caddy, Traefik)
  • Configure firewall rules
  • Set NODE_ENV=production
  • Enable log rotation
  • Configure monitoring and health checks
  • Review and restrict ALLOW_REGISTRATION setting
  • Set up external authentication (OAuth, LDAP) if needed

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us