Docker Compose Deployment

Docker Compose provides a complete multi-container deployment of LibreChat with all required dependencies. This is the recommended approach for local development and testing.

Prerequisites

Docker Engine 20.10 or later
Docker Compose V2 (docker compose) or V1 (docker-compose)
At least 4GB of available RAM
20GB of free disk space

Architecture Overview

The Docker Compose setup includes:

LibreChat API: Main application server
MongoDB: Database for conversations and user data
Meilisearch: Search engine for message indexing
Vector DB: PostgreSQL with pgvector for RAG functionality
RAG API: Retrieval-Augmented Generation service

Development Setup (docker-compose.yml)

The standard docker-compose.yml is designed for development with live mounting of configuration files.

Configuration

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_PORT=${RAG_PORT:-8000}
      - RAG_API_URL=http://rag_api:${RAG_PORT:-8000}
    volumes:
      - type: bind
        source: ./.env
        target: /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
    user: "${UID}:${GID}"
    environment:
      - MEILI_HOST=http://meilisearch:7700
      - MEILI_NO_ANALYTICS=true
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
    volumes:
      - ./meili_data_v1.35.1:/meili_data

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

  rag_api:
    container_name: rag_api
    image: registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest
    environment:
      - DB_HOST=vectordb
      - RAG_PORT=${RAG_PORT:-8000}
    restart: always
    depends_on:
      - vectordb
    env_file:
      - .env

volumes:
  pgdata2:

Getting Started

Clone the Repository

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

Configure Environment

Copy the example environment file:

cp .env.example .env

Set required variables in .env:

# User/Group IDs (run 'id' command to get yours)
UID=1000
GID=1000

# Application Port
PORT=3080

# Meilisearch Master Key
MEILI_MASTER_KEY=your-secure-master-key

# Authentication
JWT_SECRET=your-jwt-secret
JWT_REFRESH_SECRET=your-refresh-secret
CREDS_KEY=your-creds-key
CREDS_IV=your-creds-iv

# API Keys
OPENAI_API_KEY=your-openai-key

Start Services

Launch all services:

docker compose up -d

Check status:

docker compose ps

Access LibreChat

Open your browser to:

http://localhost:3080

Production Setup (deploy-compose.yml)

The deploy-compose.yml configuration is optimized for production with separate API and NGINX containers.

Configuration

services:
  api:
    image: registry.librechat.ai/danny-avila/librechat-dev-api:latest
    container_name: LibreChat-API
    ports:
      - 3080:3080
    depends_on:
      - mongodb
      - rag_api
    restart: always
    extra_hosts:
      - "host.docker.internal:host-gateway"
    env_file:
      - .env
    environment:
      - HOST=0.0.0.0
      - NODE_ENV=production
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
      - MEILI_HOST=http://meilisearch:7700
      - RAG_PORT=${RAG_PORT:-8000}
      - RAG_API_URL=http://rag_api:${RAG_PORT:-8000}
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
      - ./images:/app/client/public/images
      - ./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
    restart: always
    volumes:
      - ./client/nginx.conf:/etc/nginx/conf.d/default.conf

  mongodb:
    container_name: chat-mongodb
    image: mongo:8.0.17
    restart: always
    volumes:
      - ./data-node:/data/db
    command: mongod --noauth

  meilisearch:
    container_name: chat-meilisearch
    image: getmeili/meilisearch:v1.35.1
    restart: always
    env_file:
      - .env
    environment:
      - MEILI_HOST=http://meilisearch:7700
      - MEILI_NO_ANALYTICS=true
    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
    restart: always
    volumes:
      - pgdata2:/var/lib/postgresql/data

  rag_api:
    image: registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest
    environment:
      - DB_HOST=vectordb
      - RAG_PORT=${RAG_PORT:-8000}
    restart: always
    depends_on:
      - vectordb
    env_file:
      - .env

volumes:
  pgdata2:

The production setup requires a librechat.yaml configuration file. Create this file before deploying.

Service Details

LibreChat API

Image: registry.librechat.ai/danny-avila/librechat-dev:latest
Port: Configurable via ${PORT} (default: 3080)
Dependencies: MongoDB, Meilisearch, RAG API

MongoDB

Image: mongo:8.0.17
Port: 27017 (internal only)
Data: Stored in ./data-node
Authentication: Disabled by default (use --auth for production)

For production, enable MongoDB authentication:

command: mongod --auth

Then configure MONGO_URI with credentials.

Meilisearch

Image: getmeili/meilisearch:v1.35.1
Port: 7700 (internal only)
Data: Stored in ./meili_data_v1.35.1
Master Key: Required via MEILI_MASTER_KEY

Vector Database (PostgreSQL + pgvector)

Image: pgvector/pgvector:0.8.0-pg15-trixie
Port: 5432 (internal only)
Purpose: Stores embeddings for RAG functionality
Data: Persistent volume pgdata2

RAG API

Image: registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite:latest
Port: Configurable via ${RAG_PORT} (default: 8000)
Purpose: Provides retrieval-augmented generation capabilities

Port Mappings

Service	Internal Port	External Port	Protocol
LibreChat	3080	$ (3080)	HTTP
MongoDB	27017	-	TCP
Meilisearch	7700	-	HTTP
Vector DB	5432	-	TCP
RAG API	8000	-	HTTP
NGINX (prod)	80, 443	80, 443	HTTP/HTTPS

Volume Management

Application Data

./images          # User-uploaded images
./uploads         # File uploads
./logs            # Application logs
./data-node       # MongoDB data
./meili_data_v1.35.1  # Meilisearch index

Backup Volumes

# Backup MongoDB
docker compose exec mongodb mongodump --out /data/db/backup

# Backup all data
tar -czf librechat-backup.tar.gz images uploads logs data-node meili_data_v1.35.1

Customization with Override File

Never edit docker-compose.yml directly. Use docker-compose.override.yaml for customizations.

Create docker-compose.override.yaml:

services:
  api:
    environment:
      - CUSTOM_VAR=custom_value
    volumes:
      - ./custom-config:/app/custom-config

  mongodb:
    ports:
      - "27017:27017"  # Expose MongoDB externally

Apply overrides:

docker compose up -d

User Permissions

The development compose file uses ${UID}:${GID} to match host user permissions:

# Get your UID and GID
id

# Add to .env
UID=1000
GID=1000

This prevents permission issues with mounted volumes.

Common Commands

Start Services

# Start all services
docker compose up -d

# Start specific service
docker compose up -d api

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Stop Services

# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart api

Update Images

# Pull latest images
docker compose pull

# Recreate containers
docker compose up -d

Troubleshooting

Services Won’t Start

Check service health:

docker compose ps

Inspect logs:

docker compose logs api

MongoDB Connection Issues

Verify MongoDB is running:

docker compose exec mongodb mongosh --eval "db.adminCommand('ping')"

Port Conflicts

Change the port in .env:

PORT=3081

Then restart:

docker compose up -d

Permission Denied Errors

Fix volume permissions:

sudo chown -R ${UID}:${GID} images uploads logs data-node meili_data_v1.35.1

Performance Tuning

Resource Limits

Add resource limits in docker-compose.override.yaml:

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

MongoDB Optimization

mongodb:
  command: mongod --wiredTigerCacheSizeGB 1.5 --noauth

Next Steps

Configure LibreChat with librechat.yaml
Set up SSL/TLS for production
Enable MongoDB authentication
Configure reverse proxy (NGINX/Traefik)
Explore Kubernetes deployment for scaling

Get Started

Core Features

Configuration

Deployment

User Management

​Prerequisites

​Architecture Overview

​Development Setup (docker-compose.yml)

​Configuration

​Getting Started

​Production Setup (deploy-compose.yml)

​Configuration

​Service Details

​LibreChat API

​MongoDB

​Meilisearch

​Vector Database (PostgreSQL + pgvector)

​RAG API

​Port Mappings

​Volume Management

​Application Data

​Backup Volumes

​Customization with Override File

​User Permissions

​Common Commands

​Start Services

​View Logs

​Stop Services

​Restart Services

​Update Images

​Troubleshooting

​Services Won’t Start

​MongoDB Connection Issues

​Port Conflicts

​Permission Denied Errors

​Performance Tuning

​Resource Limits

​MongoDB Optimization

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Architecture Overview

Development Setup (docker-compose.yml)

Configuration

Getting Started

Production Setup (deploy-compose.yml)

Configuration

Service Details

LibreChat API

MongoDB

Meilisearch

Vector Database (PostgreSQL + pgvector)

RAG API

Port Mappings

Volume Management

Application Data

Backup Volumes

Customization with Override File

User Permissions

Common Commands

Start Services

View Logs

Stop Services

Restart Services

Update Images

Troubleshooting

Services Won’t Start

MongoDB Connection Issues

Port Conflicts

Permission Denied Errors

Performance Tuning

Resource Limits

MongoDB Optimization

Next Steps