Docker를 사용하여 LibreChat을 설치하는 방법: 완벽 가이드

LibreChat을 사용하면 ChatGPT와 유사한 AI 인터페이스를 컴퓨터나 서버에 구축할 수 있습니다. 단일 위치에서 상용 제공업체, OpenAI 호환 엔드포인트, Ollama를 통해 실행되는 모델, MCP 서버 등을 활용할 수 있습니다.

Docker를 사용하는 것이 설치 방법 중 가장 쉬운 방법 중 하나입니다. 이 시스템은 LibreChat과 관련 서비스들을 위한 별도의 컨테이너를 생성하세요.MongoDB, Meilisearch 및 기타 종속성을 수동으로 구성할 필요가 없습니다.

하지만 LibreChat을 컴퓨터에서 실행하는지 아니면 원격 Ubuntu 서버에서 실행하는지에 따라 설치 과정이 약간 다릅니다. 또한 다양한 파일의 용도를 이해하는 것도 중요합니다. .env, librechat.yaml y docker-compose.override.yml다음으로 살펴보겠습니다. Docker를 사용하여 LibreChat을 설치하는 방법 변경 사항이 손실되지 않고 업데이트할 수 있는 구성을 준비합니다.

Docker를 사용하여 LibreChat을 설치하기 위한 요구 사항

로컬 설치를 위해서는 두 가지 도구가 필요합니다.

• 깃저장소를 다운로드하고 업데이트를 수신하는 데 사용됩니다.
• 도커LibreChat과 LibreChat이 의존하는 서비스를 운영하는 책임자입니다.

Windows 및 macOS에서는 Docker Desktop을 설치하는 것이 가장 간단한 방법입니다. Linux에서는 Docker Engine과 공식 Docker Compose 플러그인을 사용할 수 있습니다.

다음 명령어를 사용하여 두 도구가 모두 사용 가능한지 확인할 수 있습니다.

git --version
docker --version
docker compose version

마지막 명령에는 Compose 버전이 표시되어야 합니다. 현재 사용 중인 버전은 다음과 같습니다. docker compose하이픈 없이 입력하세요. Compose v2는 Docker 플러그인으로 작동하기 때문입니다.

로컬 설치의 경우 Node.js 또는 NPM을 설치할 필요가 없습니다. 하지만 LibreChat 원격 배포 가이드에 포함된 특정 스크립트를 사용할 때는 이러한 도구가 필요할 수 있습니다.

우분투 서버에 Docker 설치하기

VPS나 Ubuntu 서버에서 LibreChat을 호스팅하는 경우, Docker 공식 저장소에서 Docker를 설치하는 것이 가장 좋습니다. 이렇게 하면 Docker Engine, 명령줄 인터페이스, Compose 플러그인 등 프로젝트 자체에서 관리하는 모든 구성 요소를 사용할 수 있습니다.

시작하기 전에 패키지 인덱스를 업데이트하세요.

sudo apt update
sudo apt upgrade

다음으로 Git을 설치하고 공식 Docker 절차에 따라 저장소와 패키지를 추가하세요. 설치가 완료되면 서비스가 실행 중인지 확인하십시오.

sudo systemctl status docker

다음 명령어도 실행할 수 있습니다:

sudo docker run hello-world

Docker를 사용하려면 코드를 작성하지 않고 싶다면 sudo 각 주문에서 사용자를 해당 그룹에 추가하세요.

sudo usermod -aG docker $USER

그런 다음 로그아웃했다가 다시 로그인하거나 서버를 재시작해야 합니다. 그룹 구성원도 고려해야 한다는 점을 명심하십시오. docker 그들은 시스템에 대한 매우 높은 수준의 접근 권한을 가지고 있습니다. 신뢰할 수 없는 사용자는 추가하지 마십시오.

컴퓨터에 LibreChat 설치

LibreChat을 다운로드하려면 터미널을 열고 공식 저장소를 클론하세요.

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

다음 단계는 프로젝트에 포함된 예제를 사용하여 환경 변수 파일을 생성하는 것입니다.

cp .env.example .env

Windows PowerShell에서 위 명령어를 사용할 수 없는 경우 다음 명령어를 사용하십시오.

Copy-Item .env.example .env

기본 설정은 초기 시작을 허용하지만, 인터넷에서 접근 가능한 서버에서 LibreChat을 사용하기 전에 해당 파일을 검토해야 합니다.

컨테이너를 시작하려면 다음 명령을 실행하세요.

docker compose up -d

Docker는 필요한 이미지를 다운로드하고 서비스를 생성합니다. 초기 설정에는 몇 분 정도 소요될 수 있습니다.

완료되면 브라우저에서 열어보세요.

http://localhost:3080

LibreChat에는 기본 비밀번호가 포함되어 있지 않습니다. 처음 등록하는 계정이 관리자 계정이 됩니다.따라서 다른 사람이 인스턴스에 액세스하기 전에 먼저 인스턴스를 생성하는 것이 좋습니다.

LibreChat 설정 파일 이해하기

LibreChat은 서로 다른 기능을 가진 여러 파일을 사용합니다.

• .env 이 저장소에는 API 키, 비밀 키, 인증 옵션 및 서버 변수가 저장됩니다.
• librechat.yaml 사용자 지정 엔드포인트, 모델, MCP 서버 및 기타 고급 설정을 정의합니다.
• docker-compose.yml 여기에는 Docker 서비스의 주요 정의가 포함되어 있습니다.
• docker-compose.override.yml 이 기능을 사용하면 메인 파일을 수정하지 않고도 자신만의 포트, 볼륨 및 변경 사항을 추가할 수 있습니다.

생성은 필수 사항이 아닙니다. librechat.yaml LibreChat을 시작하는 데 필요합니다. 사용자 지정 엔드포인트나 특정 고급 기능을 사용하려는 경우에만 필요합니다.

제공된 예제를 통해 생성할 수 있습니다.

cp librechat.example.yaml librechat.yaml

개인 키는 YAML 파일 내에 직접 작성해서는 안 됩니다. 개인 키는 별도의 저장소에 저장하는 것이 좋습니다. .env 변수를 사용하여 참조하세요.

컨테이너 내부에 librechat.yaml 파일을 마운트합니다.

Docker를 사용하여 LibreChat을 실행할 때 저장 librechat.yaml 프로젝트 디렉터리만으로는 충분하지 않을 수 있습니다. API 컨테이너는 해당 파일에 접근할 수 있어야 합니다.

먼저 예시로 제공된 오버라이드 파일을 복사하세요.

cp docker-compose.override.yml.example docker-compose.override.yml

그럼 이 책에 무엇이 들어 있는지 확인해 보세요.

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Docker Compose는 이 파일을 자동으로 다음 파일과 결합합니다. docker-compose.yml이렇게 하면 저장소를 업데이트할 때 사용자 지정 설정을 유지할 수 있습니다.

변경 사항을 적용하려면 서비스를 다시 생성하십시오.

docker compose down
docker compose up -d

설정된 엔드포인트가 LibreChat에 나타나지 않으면 API 로그를 확인하십시오.

docker compose logs api

오류는 대개 YAML 파일의 들여쓰기 오류나 변수 누락 때문에 발생합니다. .env 또는 제대로 조립되지 않은 책자.

원격 서버에 LibreChat 설치

LibreChat은 리소스가 제한된 Linux 서버를 위한 특정 파일을 제공합니다.

deploy-compose.yml

이 배포 방식은 사전 컴파일된 이미지를 사용하므로 서버가 애플리케이션을 로컬에서 빌드할 필요가 없습니다. 또한 웹 연결을 수신하는 NGINX 컨테이너도 포함되어 있습니다.

저장소 다운로드 및 파일 준비가 완료되면 .env다음 명령으로 배포 버전을 시작할 수 있습니다.

docker compose -f ./deploy-compose.yml up -d

그러면 다음에서 접속할 수 있습니다:

http://IP_DEL_SERVIDOR

배포 파일이 NGINX를 일반 웹 포트로 공개하기 때문에 주소가 로컬 설치 주소와 다릅니다.

인스턴스를 공개하기 전에 필요한 모든 변수에 대해 고유한 비밀 키를 생성하십시오. 예를 들어 관리자 패널 세션 비밀 키는 다음과 같이 생성할 수 있습니다.

openssl rand -hex 32

결과를 해당 변수에 복사합니다. .env 공유하거나 저장소에 게시하지 않고.

관리자 계정을 생성한 후에는 신규 사용자 등록을 비활성화할 수도 있습니다.

ALLOW_REGISTRATION=false

환경 변수에 대한 변경 사항을 적용하려면 서비스를 다시 시작하십시오.

도메인을 설정하고 HTTPS를 사용하여 LibreChat을 보호하세요.

NGINX에서 서버 이름만 수정하는 것으로는 설치 보안을 확보하기에 충분하지 않습니다. 먼저 도메인이 서버의 IP 주소를 가리키도록 DNS 레코드를 생성해야 합니다.

다음으로, Let's Encrypt와 같은 TLS 인증서를 발급받고 NGINX가 해당 인증서를 사용하도록 구성해야 합니다. NGINX를 패키지에 포함하여 실행하는 경우 deploy-compose.yml컨테이너 내부에 인증서 파일도 마운트해야 합니다.

En client/nginx.conf기본 지침이 다음과 같이 변경됩니다.

server_name localhost;

a:

server_name chat.ejemplo.com;

또한 LibreChat 도메인 변수를 올바르게 구성해야 합니다. .env 그리고 해당 아키텍처에 맞는 인증 절차를 따르십시오.

HTTP를 통해 사용자 계정이 포함된 인스턴스를 게시하지 마십시오. LibreChat이 인터넷에서 접근 가능한 경우 HTTPS, 강력한 암호, 방화벽 및 영구 볼륨 백업을 사용하십시오.

LibreChat 포트를 3080으로 변경하세요

다른 애플리케이션이 3080번 포트를 사용 중인 경우 Docker는 다음과 유사한 오류를 표시합니다. bind: address already in use.

메인 파일을 수정할 필요가 없습니다. 이 설정을 추가하세요. docker-compose.override.yml:

services:
  api:
    ports:
      - "3081:3080"

컨테이너를 다시 생성하세요:

docker compose down
docker compose up -d

그 순간부터 다음 명령어를 사용하여 LibreChat을 열 수 있습니다.

http://localhost:3081

이 예시는 로컬 Compose에 해당합니다. 만약 사용하신다면 deploy-compose.yml연결이 NGINX 컨테이너를 통해 이루어진다는 점을 유념해야 합니다.

컨테이너가 닫혀 있을 경우 어떻게 해야 할까요?

서비스 상태를 확인하려면 다음 명령을 실행하세요.

docker compose ps

그다음 API 컨테이너 로그를 확인하세요.

docker compose logs api

실시간으로 메시지를 확인할 수도 있습니다.

docker compose logs -f api

가장 흔한 원인은 다음과 같습니다.

• 파일 .env 해당 파일은 프로젝트의 루트 디렉토리에 있지 않습니다.
• librechat.yaml 구문 오류 또는 들여쓰기 오류가 있습니다.
• 필수 변수가 누락되었습니다.
• Docker가 시작되지 않았습니다.
• 필수 포트가 다른 프로그램에서 사용 중입니다.
• 서버 시작 중에 메모리가 부족해졌습니다.

변수가 컨테이너에 도달했는지 확인하려면 다음을 사용할 수 있습니다.

docker compose exec api env | grep -i NOMBRE_DE_LA_VARIABLE

이 명령의 전체 출력 결과를 공개 스크린샷에 표시하지 마십시오. 환경 변수에 자격 증명이 포함될 수 있습니다.

Docker로 설치된 LibreChat을 업데이트하는 방법

로컬 설치의 경우, LibreChat 문서에서는 서비스를 중지하고, 저장소에서 변경 사항을 다운로드하고, 업데이트된 이미지를 가져오는 것을 권장합니다.

docker compose down
git pull
docker compose pull
docker compose up -d

원격 배포를 사용하고 프로젝트 스크립트를 사용할 수 있는 경우 다음 명령을 실행할 수 있습니다.

npm run update:deployed

수동으로 작업하는 것도 가능합니다.

docker compose -f ./deploy-compose.yml down
git pull
docker compose -f ./deploy-compose.yml pull
docker compose -f ./deploy-compose.yml up -d

Git으로 관리되는 파일을 직접 수정했다면 업데이트 시 충돌이 발생할 수 있습니다. 따라서 사용자 지정 변경 사항은 별도의 폴더에 저장하는 것이 좋습니다. .env, librechat.yaml 가능한 경우 파일을 덮어쓰세요.

기본 원격 구성은 메인 브랜치에서 컴파일된 이미지를 따를 수 있습니다. 안정성이 최우선이라면 LibreChat에서 게시한 태그를 검토하고 안정적인 버전을 명시적으로 구성하십시오. 단, 이 경우 새로 추가되는 기능은 더 이상 수신되지 않습니다.

Docker를 사용하여 LibreChat을 설치하면 시스템에 불필요한 종속성을 추가하지 않고도 로컬 모델과 외부 공급자를 단일 인터페이스에서 통합할 수 있습니다. 핵심은 적절한 Compose 파일을 선택하고, 비밀 정보와 설정을 적절히 분리하고, 원격 액세스를 보호하고, 사용자 정의 설정을 메인 프로젝트 파일 외부에 유지하는 것입니다.

인스턴스가 실행되면 다음 단계는 Ollama, OpenRouter, 상용 제공업체 등을 추가하는 것일 수 있습니다. MCP 서버를 LibreChat에 연결하세요.