LibreChat Docker 설치 가이드: 멀티 AI ChatGPT 클론 ⋆ Blog * JackerLab

개요

LibreChat는 모든 주요 AI 제공자를 하나의 인터페이스에서 사용할 수 있는 오픈소스 ChatGPT 클론입니다. OpenAI, Anthropic, Google, Azure, Ollama 등 다양한 AI 모델을 연결하고, 대화 중에 자유롭게 전환할 수 있습니다. AI 에이전트, MCP, 코드 인터프리터, Artifacts, 멀티모달 대화, 메시지 검색 등 고급 기능을 제공합니다.

항목	내용
GitHub	https://github.com/danny-avila/LibreChat
공식 사이트	https://librechat.ai
문서	https://docs.librechat.ai
라이선스	MIT
GitHub Stars	20K+

LibreChat란?

왜 LibreChat인가?

❌ 기존 ChatGPT 문제점:
   - 단일 AI 제공자만 사용
   - 월 $20 구독료
   - 데이터 프라이버시 우려

✅ LibreChat의 해결책:
   - 모든 AI를 하나의 UI에서
   - API 비용만 지불 (또는 무료 로컬 LLM)
   - 완전한 데이터 통제
   - ChatGPT Plus 기능 + 추가 기능

핵심 슬로건

"Every AI for Everyone"
- OpenAI, Anthropic, Google, Azure 등 통합
- 대화 중 모델 전환
- ChatGPT UI + 향상된 기능
- 완전 오픈소스, 셀프호스팅

아키텍처

┌─────────────────────────────────────────────┐
│              LibreChat UI                    │
├─────────────────────────────────────────────┤
│           Node.js API Server                 │
├──────────────┬──────────────┬───────────────┤
│   MongoDB    │  MeiliSearch │  RAG API      │
│  (대화 저장) │   (검색)     │  (문서 RAG)   │
└──────────────┴──────────────┴───────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│  OpenAI │ Anthropic │ Google │ Azure │ ...  │
└─────────────────────────────────────────────┘

주요 기능

🤖 AI 제공자 통합

제공자	지원 모델
OpenAI	GPT-4o, GPT-4, GPT-3.5, o1, o3
Anthropic	Claude 3.5, Claude 3
Google	Gemini Pro, Gemini Ultra
Azure OpenAI	엔터프라이즈 GPT
AWS Bedrock	Claude, Llama 등
Ollama	로컬 LLM
OpenRouter	모든 모델 통합
Groq	초고속 추론
Mistral	Mistral Large, Medium
Custom	OpenAI 호환 API

🎨 UI & 경험

기능	설명
ChatGPT 스타일 UI	친숙한 인터페이스
모델 전환	대화 중 AI 변경
대화 포킹	대화 분기
메시지 검색	전체 대화 검색
프리셋	커스텀 설정 저장
다국어	40+ 언어 지원 (한국어 포함)

🛠️ 고급 기능

기능	설명
AI Agents	도구 사용 에이전트
MCP	Model Context Protocol
Code Interpreter	코드 실행
Artifacts	React, 다이어그램 렌더링
DALL-E 3	이미지 생성
Vision	이미지 분석 (GPT-4V, Claude Vision)
파일 업로드	PDF, 문서 채팅
OpenAPI Actions	외부 API 통합

🔐 보안 & 인증

기능	설명
멀티 유저	다중 사용자 지원
OAuth2	Google, GitHub, Discord 등
LDAP	엔터프라이즈 인증
Keycloak	SSO 통합
모더레이션	콘텐츠 필터링

📚 RAG & 지식

기능	설명
RAG API	문서 검색 증강
파일 업로드	PDF, DOCX, TXT 등
벡터 검색	PostgreSQL + pgvector
MeiliSearch	대화 검색

시스템 요구 사항

항목	최소	권장
CPU	2 코어	4+ 코어
RAM	4GB	8GB+
저장소	10GB	20GB+
포트	3080	–

Docker 설치

방법 1: 공식 Docker Compose (권장)

# 저장소 클론
git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat

# 환경 설정
cp .env.example .env
# .env 파일 편집하여 API 키 설정

# librechat.yaml 생성 (선택)
cp librechat.example.yaml librechat.yaml

# 시작
docker compose up -d

접속: http://localhost:3080

방법 2: 간소화된 Docker Compose

# docker-compose.yml
services:
  librechat:
    image: ghcr.io/danny-avila/librechat:latest
    container_name: librechat
    restart: unless-stopped
    ports:
      - "3080:3080"
    depends_on:
      - mongodb
      - meilisearch
    environment:
      - HOST=0.0.0.0
      - MONGO_URI=mongodb://mongodb:27017/LibreChat
      - MEILI_HOST=http://meilisearch:7700
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./images:/app/client/public/images
      - ./logs:/app/api/logs

  mongodb:
    image: mongo:latest
    container_name: librechat-mongodb
    restart: unless-stopped
    volumes:
      - ./data-node:/data/db

  meilisearch:
    image: getmeili/meilisearch:latest
    container_name: librechat-meilisearch
    restart: unless-stopped
    environment:
      - MEILI_MASTER_KEY=${MEILI_MASTER_KEY:-your-master-key}
    volumes:
      - ./meili_data:/meili_data

.env 파일:

OPENAI_API_KEY=sk-your-key
MEILI_MASTER_KEY=your-master-key-at-least-16-bytes

방법 3: Anthropic Claude 추가

.env 파일:

OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=sk-ant-your-key

방법 4: Google Gemini 추가

.env 파일:

GOOGLE_API_KEY=your-google-api-key
# 또는 Vertex AI
GOOGLE_PROJECT_ID=your-project-id
GOOGLE_LOCATION=us-central1

방법 5: Ollama 로컬 LLM

# docker-compose.override.yml
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ./ollama:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

librechat.yaml:

endpoints:
  custom:
    - name: "Ollama"
      apiKey: "ollama"
      baseURL: "http://ollama:11434/v1"
      models:
        default: ["llama3.2", "mistral", "codellama"]
        fetch: true

방법 6: RAG API (문서 RAG)

# docker-compose.override.yml
services:
  rag_api:
    image: ghcr.io/danny-avila/librechat-rag-api-dev:latest
    container_name: librechat-rag-api
    restart: unless-stopped
    depends_on:
      - vectordb
    environment:
      - DB_HOST=vectordb
      - RAG_PORT=8000
    volumes:
      - ./uploads:/app/uploads

  vectordb:
    image: pgvector/pgvector:pg16
    container_name: librechat-vectordb
    restart: unless-stopped
    environment:
      - POSTGRES_DB=mydatabase
      - POSTGRES_USER=myuser
      - POSTGRES_PASSWORD=mypassword
    volumes:
      - ./pgvector:/var/lib/postgresql/data

.env 추가:

RAG_API_URL=http://rag_api:8000

방법 7: OAuth2 인증 (Google)

.env 파일:

ALLOW_SOCIAL_LOGIN=true
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_CALLBACK_URL=/oauth/google/callback

방법 8: Traefik + HTTPS

# docker-compose.override.yml
services:
  librechat:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.librechat.rule=Host(`chat.example.com`)"
      - "traefik.http.routers.librechat.entrypoints=websecure"
      - "traefik.http.routers.librechat.tls.certresolver=letsencrypt"
      - "traefik.http.services.librechat.loadbalancer.server.port=3080"
    networks:
      - traefik_network

networks:
  traefik_network:
    external: true

환경 변수

기본 설정

변수	설명	기본값
`HOST`	바인딩 주소	`0.0.0.0`
`PORT`	서버 포트	`3080`
`ALLOW_REGISTRATION`	회원가입 허용	`true`
`ALLOW_SOCIAL_LOGIN`	소셜 로그인	`false`

AI 제공자

변수	설명
`OPENAI_API_KEY`	OpenAI API 키
`ANTHROPIC_API_KEY`	Anthropic API 키
`GOOGLE_API_KEY`	Google AI API 키
`AZURE_API_KEY`	Azure OpenAI 키
`OPENROUTER_API_KEY`	OpenRouter 키

데이터베이스

변수	설명
`MONGO_URI`	MongoDB 연결 문자열
`MEILI_HOST`	MeiliSearch URL
`MEILI_MASTER_KEY`	MeiliSearch 마스터 키 (16바이트+)

RAG

변수	설명
`RAG_API_URL`	RAG API 서버 URL
`RAG_PORT`	RAG API 포트

인증

변수	설명
`JWT_SECRET`	JWT 시크릿
`JWT_REFRESH_SECRET`	JWT 리프레시 시크릿
`CREDS_KEY`	자격 증명 암호화 키
`CREDS_IV`	자격 증명 IV

OAuth2

변수	설명
`GOOGLE_CLIENT_ID`	Google OAuth 클라이언트 ID
`GOOGLE_CLIENT_SECRET`	Google OAuth 시크릿
`GITHUB_CLIENT_ID`	GitHub OAuth 클라이언트 ID
`GITHUB_CLIENT_SECRET`	GitHub OAuth 시크릿

librechat.yaml 설정

고급 설정을 위한 YAML 설정 파일:

# librechat.yaml
version: 1.2.1

cache: true

fileStrategy: "local"

registration:
  socialLogins: ["google", "github"]

endpoints:
  # OpenAI 설정
  openAI:
    titleModel: "gpt-4o-mini"
    plugins: true
  
  # Anthropic 설정
  anthropic:
    titleModel: "claude-3-haiku-20240307"
  
  # 커스텀 엔드포인트 (Ollama 등)
  custom:
    - name: "Ollama"
      apiKey: "ollama"
      baseURL: "http://ollama:11434/v1"
      models:
        default: ["llama3.2", "mistral", "codellama"]
        fetch: true
      titleConvo: true
      titleModel: "llama3.2"
    
    - name: "OpenRouter"
      apiKey: "${OPENROUTER_API_KEY}"
      baseURL: "https://openrouter.ai/api/v1"
      models:
        fetch: true

# 모델 스펙
modelSpecs:
  enforce: false
  prioritize: true
  list:
    - name: "gpt-4o"
      label: "GPT-4o (Omni)"
      description: "최신 GPT-4 멀티모달 모델"
      iconURL: "https://example.com/openai-icon.svg"

Docker에서 librechat.yaml 마운트

# docker-compose.override.yml
services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

초기 설정

1) 첫 접속

URL: http://localhost:3080
→ 계정 생성
→ 로그인

2) AI 제공자 선택

채팅 화면 상단에서 AI 제공자 선택
모델 선택
채팅 시작

3) 프리셋 만들기

설정 아이콘 클릭
Save Preset 선택
이름, 시스템 프롬프트, 파라미터 설정
저장

4) 파일 업로드 (RAG)

채팅 입력창 옆 파일 아이콘 클릭
PDF, DOCX, TXT 등 업로드
파일 내용 기반 질문

사용 가이드

모델 전환

대화 중 언제든 다른 AI로 전환:

상단 모델 선택기 클릭
다른 제공자/모델 선택
동일 대화에서 다른 AI 응답 받기

AI 에이전트 사용

Agents 선택
도구 활성화 (웹 검색, 코드 실행 등)
에이전트가 도구 사용하여 답변

Artifacts

코드, 다이어그램, React 컴포넌트를 대화 내에서 렌더링:

Claude의 Artifacts 기능과 유사
실시간 미리보기

대화 검색

좌측 사이드바 검색창
키워드 입력
전체 대화 내역에서 검색

대화 포킹

메시지에서 포크 아이콘 클릭
해당 지점부터 새 대화 분기
다른 방향으로 대화 진행

백업 및 복원

데이터 구조

./
├── data-node/      # MongoDB 데이터
├── meili_data/     # MeiliSearch 인덱스
├── images/         # 업로드 이미지
├── logs/           # 로그
└── uploads/        # RAG 문서 (사용 시)

백업

# 컨테이너 정지
docker compose down

# 전체 백업
tar -czvf librechat-backup-$(date +%Y%m%d).tar.gz \
  data-node/ meili_data/ images/ .env

# 컨테이너 재시작
docker compose up -d

복원

tar -xzvf librechat-backup.tar.gz
docker compose up -d

업데이트

# 최신 변경사항 가져오기
git pull

# 이미지 업데이트
docker compose pull

# 재시작
docker compose down
docker compose up -d

트러블슈팅

MongoDB 연결 실패

# MongoDB 로그 확인
docker compose logs mongodb

ARM CPU (라즈베리파이)의 경우:

mongodb:
  image: mongo:4.4.18

MeiliSearch 마스터 키 오류

마스터 키는 최소 16바이트 필요:

MEILI_MASTER_KEY=this-key-must-be-at-least-16-bytes-long

Ollama 연결 안 됨

librechat.yaml에서 URL 확인:

baseURL: "http://ollama:11434/v1"  # Docker 네트워크
# 또는
baseURL: "http://host.docker.internal:11434/v1"  # 호스트

이미지 태그

태그	설명
`latest`	안정 버전
`dev`	개발 버전 (최신 기능)
`v0.x.x`	특정 버전

대안 비교

기능	LibreChat	Open WebUI	LobeChat
ChatGPT UI	✅ 동일	✅ 유사	✅ 현대적
멀티 AI	✅ 다양	✅ Ollama 중심	✅
에이전트	✅	✅	✅
Artifacts	✅	❌	✅
MCP	✅	❌	❌
대화 검색	✅ MeiliSearch	✅	✅
멀티 유저	✅	✅	✅
OAuth	✅ 다양	✅	✅
설치 난이도	중간	쉬움	쉬움

선택 가이드

용도	추천
다양한 AI 통합	LibreChat
Ollama 중심	Open WebUI
현대적 UI	LobeChat
엔터프라이즈 인증	LibreChat

활용 사례

1. 개인 AI 허브

목적: 모든 AI를 하나의 인터페이스에서

OpenAI, Claude, Gemini 연결
대화 중 모델 비교
API 비용만 지불

2. 팀 AI 플랫폼

목적: 팀 공용 AI 채팅

멀티 유저 계정
OAuth 로그인
대화 기록 공유

3. 로컬 AI (프라이버시)

목적: 데이터 외부 전송 없음

Ollama 로컬 LLM
완전 오프라인 가능
민감한 데이터 처리

4. 문서 기반 Q&A

목적: RAG 기반 지식 베이스

RAG API 활성화
문서 업로드
문서 기반 답변

5. AI 에이전트 테스트

목적: 다양한 에이전트 실험

MCP 지원
커스텀 도구
코드 인터프리터

마무리

LibreChat는 모든 AI를 하나의 인터페이스에서 사용할 수 있는 강력한 ChatGPT 클론입니다. 친숙한 UI와 함께 모델 전환, 에이전트, MCP, Artifacts 등 고급 기능을 제공합니다.

핵심 장점

장점	설명
멀티 AI	OpenAI, Anthropic, Google, Ollama 등
ChatGPT UI	친숙한 인터페이스
모델 전환	대화 중 AI 변경
에이전트	도구 사용, MCP
Artifacts	코드/다이어그램 렌더링
멀티 유저	팀 사용 가능
OAuth	Google, GitHub 등 SSO
RAG	문서 기반 Q&A

이런 분께 추천

여러 AI를 비교하며 사용하고 싶은 분
ChatGPT Plus 대신 셀프호스팅 원하는 분
팀용 AI 채팅 플랫폼이 필요한 분
Ollama 로컬 LLM을 UI로 사용하고 싶은 분
에이전트, MCP 기능을 활용하려는 분

개요

LibreChat란?

왜 LibreChat인가?

핵심 슬로건

아키텍처

주요 기능

🤖 AI 제공자 통합

🎨 UI & 경험

🛠️ 고급 기능

🔐 보안 & 인증

📚 RAG & 지식

시스템 요구 사항

Docker 설치

방법 1: 공식 Docker Compose (권장)

방법 2: 간소화된 Docker Compose

방법 3: Anthropic Claude 추가

방법 4: Google Gemini 추가

방법 5: Ollama 로컬 LLM

방법 6: RAG API (문서 RAG)

방법 7: OAuth2 인증 (Google)

방법 8: Traefik + HTTPS

환경 변수

기본 설정

AI 제공자

데이터베이스

RAG

인증

OAuth2

librechat.yaml 설정

Docker에서 librechat.yaml 마운트

초기 설정

1) 첫 접속

2) AI 제공자 선택

3) 프리셋 만들기

4) 파일 업로드 (RAG)

사용 가이드

모델 전환

AI 에이전트 사용

Artifacts

대화 검색

대화 포킹

백업 및 복원

데이터 구조

백업

복원

업데이트

트러블슈팅

MongoDB 연결 실패

MeiliSearch 마스터 키 오류

Ollama 연결 안 됨

이미지 태그

대안 비교

선택 가이드

활용 사례

1. 개인 AI 허브

2. 팀 AI 플랫폼

3. 로컬 AI (프라이버시)

4. 문서 기반 Q&A

5. AI 에이전트 테스트

마무리

핵심 장점

이런 분께 추천

댓글 남기기 응답 취소