Docker Deployment

Deploy LibreChat using Docker and Docker Compose

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:

Variable	Description	Default
PORT	Application port	3080
HOST	Bind address	0.0.0.0
MONGO_URI	MongoDB connection string	mongodb://mongodb:27017/LibreChat
MEILI_HOST	Meilisearch endpoint	http://meilisearch:7700
RAG_API_URL	RAG API endpoint	http://rag_api:8000
UID	User ID for file permissions	1000
GID	Group ID for file permissions	1000
NODE_ENV	Environment mode	production

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

• Configure AI Endpoints
• Set up OAuth Authentication
• Enable RAG API
• Customize UI with librechat.yaml