Docker (원격 Linux)

이 가이드를 사용하려면 원격 컴퓨터나 VM이 배포되어 있어야 합니다. 로컬 설치 환경에서도 이 가이드를 사용할 수는 있지만, 본래 클라우드 배포를 위해 작성되었다는 점을 유념해 주십시오.

⚠️ 이 가이드는 원래 Digital Ocean을 기준으로 작성되었으므로, 다른 플랫폼을 사용하는 경우 지침을 수정해야 할 수도 있지만 핵심 개념은 동일하게 유지됩니다.

Part I: Docker 및 기타 종속성 설치하기:

Linux 시스템에서 Docker를 설정하는 방법은 여러 가지가 있습니다. 이 가이드를 바탕으로 가장 권장되는 최선의 방법을 안내해 드리겠습니다.

Ubuntu Docker 설치를 위한 "최고의(Best)" 방법이 반드시 "가장 빠른" 방법이나 "가장 쉬운" 방법을 의미하는 것은 아닙니다. 이는 장기적인 이점(예: 더 빠른 업데이트, 보안 패치 등)을 고려했을 때 가장 권장되는 설치 방법을 의미합니다.

1. Docker 종속성 업데이트 및 설치

먼저, 패키지 목록을 업데이트하고 필요한 Docker 종속성을 설치하겠습니다.

sudo apt update

그런 다음, 다음 명령어를 사용하여 의존성 또는 필수 패키지를 설치하세요.

sudo apt install apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

설치 참고 사항

• 이 가이드 전체에 걸쳐 나타나는 모든 [Y/n] (yes/no) 터미널 프롬프트에 대해 "Y"를 입력하십시오.
• 첫 번째 [Y/n] 프롬프트 이후, 서비스를 다시 시작하라는 보라색 화면이 몇 번 나타나게 됩니다.
  • 이런 일이 발생할 때마다, 이미 선택된 기본 옵션을 그대로 사용하려면 안전하게 ENTER 키를 누르면 됩니다:

• 드롭릿(droplet) 콘솔 연결이 끊어지면 다음을 수행한 후 중단했던 부분부터 다시 시작하세요:
  • 위에서 설명한 대로 다시 콘솔에 액세스하세요
  • su - <yourusername> 명령어를 사용하여 생성한 사용자로 전환하세요.

2. Docker 저장소를 APT 소스에 추가

Ubuntu 저장소에서 Docker Engine을 설치하는 것이 더 쉽지만, 공식 Docker 저장소를 추가하면 더 빠른 업데이트를 받을 수 있습니다. 이것이 권장되는 방법인 이유입니다.

먼저, Docker 저장소에 연결하는 데 필요한 GPG 키를 가져오겠습니다. 이를 위해 다음 명령어를 사용하세요.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

다음으로, 저장소를 소스 목록에 추가합니다. 수동으로 추가할 수도 있지만, 아래 명령어를 사용하면 자동으로 추가됩니다.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

위 명령은 릴리스 코드명(22.04의 경우 jammy, 20.04의 경우 focal, 18.04의 경우 bionic)을 자동으로 채워줍니다.

마지막으로, 패키지를 다시 새로고침하세요.

sudo apt update

GPG 키 추가를 잊으셨다면, 위 단계에서 오류 메시지가 발생하며 실패하게 됩니다. 그렇지 않다면, Ubuntu에 Docker를 설치하는 과정을 계속 진행하겠습니다.

3. Docker 설치

docker.io와 docker-ce의 차이점은 무엇인가요?

docker.io는 일부 인기 있는 Linux 배포판(예: Ubuntu/Debian)에서 제공하는 docker 패키지입니다. 반면, docker-ce는 공식 Docker 저장소에서 제공하는 docker 패키지입니다. 일반적으로 docker-ce가 더 최신 버전이며 권장됩니다.

이제 docker-ce(docker.io 패키지가 아님)를 설치하겠습니다.

sudo apt install docker-ce

보라색 화면은 ENTER 키를 누르라는 의미입니다. :)

권장 사항: 명령어를 원활하게 사용하려면 생성된 사용자가 docker 그룹에 추가되었는지 확인해야 합니다:

sudo usermod -aG docker $USER

이제 시스템을 재부팅하여 모든 것이 정상인지 확인해 보겠습니다.

sudo reboot

재부팅 후, 브라우저 드롭릿 콘솔을 사용하는 경우, 새로고침을 클릭하고 콘솔로 다시 돌아올 때까지 기다릴 수 있습니다.

알림: sudo reboot 명령어로 재부팅할 때마다, 이전에 설정한 사용자로 su - <yourusername>을 사용하여 전환해야 합니다.

4. Ubuntu에서 Docker가 실행 중인지 확인

Ubuntu에서 Docker가 실행 중인지 확인하는 방법은 여러 가지가 있습니다. 한 가지 방법은 다음 명령어를 사용하는 것입니다:

sudo systemctl status docker

상태가 **active (running)**으로 표시되는 출력을 확인하실 수 있습니다.

CTRL (또는 CMD) + C를 눌러 이 로그를 종료하세요.

5. Docker Compose 설치

2단계에서 이미 Docker의 공식 저장소를 추가했으므로, 공식 Compose 플러그인을 사용하여 Docker Compose를 간단하게 설치할 수 있습니다:

sudo apt install docker-compose-plugin

설치 확인:

docker compose version

참고: Docker Compose v2는 기존의 docker-compose 대신 docker compose 명령어(하이픈 없음)를 사용합니다. 이 가이드의 모든 명령어는 최신 구문을 사용합니다.

6. 이 가이드의 일환으로, git과 npm을 설치하는 것을 권장합니다:

기술적으로 필수 사항은 아니지만, git과 npm을 사용하면 설치 및 업데이트가 매우 간편해집니다:

sudo apt install git nodejs npm

매트릭스 라인을 불러오세요.

다음 명령어를 통해 해당 패키지들이 성공적으로 설치되었는지 확인할 수 있습니다:

git --version
node -v
npm -v

참고: 이 방법은 구버전 Node.js 및 npm을 설치할 수 있습니다. LibreChat을 호스트에서 직접 실행하는 경우, Node.js v24.16.0 및 npm v11.16.0을 사용하세요. 이 Docker 기반 가이드의 경우, LibreChat이 컨테이너 내부에서 실행되므로 호스트의 Node.js 버전은 중요하지 않습니다.

좋습니다. 이제 Droplet 설정이 완료되었으니, 애플리케이션 자체를 설정할 차례입니다.

2부: LibreChat 설정

1. 저장소 복제(Clone down the repo)

droplet 명령줄에서 (root가 아닌 사용자 계정으로):

# clone down the repository
git clone https://github.com/danny-avila/LibreChat.git

# enter the project directory
cd LibreChat/

2. LibreChat 설정 및 환경 파일 생성

Config (librechat.yaml) 파일

다음으로, LibreChat 설정 파일, 일명 librechat.yaml을 생성하여 앱 설정 및 사용자 지정 엔드포인트를 사용자 지정할 수 있습니다.

앱을 추가로 사용자 지정할지 여부와 관계없이, 우리가 사용하는 deploy-compose.yml 파일에 필요하므로 시작을 위한 최소한의 값으로 파일을 생성할 수 있습니다:

nano librechat.yaml

편집기 화면으로 들어가면 다음을 붙여넣을 수 있습니다:

# For more information, see the Configuration Guide:
# https://www.librechat.ai/docs/configuration/librechat_yaml

# Configuration version (required)
version: 1.3.5
# This setting caches the config file for faster loading across app lifecycle
cache: true

CTRL + X를 눌러 편집기를 종료한 다음, Y를 눌러 저장하고 ENTER를 눌러 확인하세요.

환경 (.env) 파일

기본값만으로도 앱을 시작하고 실행하기에 충분하며, 웹 앱에서 직접 자격 증명을 입력할 수 있습니다.

# Copies the example file as your global env file
cp .env.example .env

하지만 보안 강화를 위해 "secret" 값을 기본값에서 변경하는 것을 강력히 권장합니다. 변경하지 않을 경우 API 시작 로그에 경고가 표시됩니다.

편의를 위해 다음을 실행하여 직접 값을 생성할 수 있습니다:

https://www.librechat.ai/toolkit/creds_generator

nano .env

# FIND THESE VARIABLES AND REPLACE THEIR DEFAULT VALUES!

# Must be a 16-byte IV (32 characters in hex)

CREDS_IV=e2341419ec3dd3d19b13a1a87fafcbfb

# Must be 32-byte keys (64 characters in hex)

CREDS_KEY=f34be427ebb29de8d88c107a71546019685ed8b241d8f2ed00c3df97ad2566f0
JWT_SECRET=16f8c0ef4a5d391b26034086c628469d3f9f497f08163ab9b40137092f2909ef
JWT_REFRESH_SECRET=eaa5191f2914e30b9387fd84e254e4ba6fc51b4654968a9b0803b456a54b8418

인스턴스의 모든 사용자가 사용할 수 있도록 자격 증명을 제공하려면, 이 파일을 편집하는 동안 해당 자격 증명을 추가해야 합니다:

OPENAI_API_KEY=sk-yourKey

이전과 마찬가지로 CTRL + X를 눌러 편집기를 종료한 다음, Y를 눌러 저장하고 ENTER를 눌러 확인합니다.

이제 끝입니다!

하지만 철저한 구성을 위해서는 필요에 따라 .env 파일을 편집해야 하며, 파일 내의 주석과 아래 리소스를 반드시 읽어보시기 바랍니다.

# if editing the .env file
nano .env

이것은 주의해야 할 환경 변수 중 하나입니다. 계정을 생성한 후 설정하고 싶을 경우를 대비해 외부 가입을 비활성화합니다.

ALLOW_REGISTRATION=false

리소스:

• 토큰/API/기타
• 사용자/인증 시스템

3. Docker 시작하기

# should already be running, but just to be safe
sudo systemctl start docker

# confirm docker is running
docker info

이제 앱 컨테이너를 시작할 수 있습니다. 처음에는 전체 명령어를 사용하고, 나중에는 단축 명령어를 사용할 수 있습니다.

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

원하신다면 터미널을 닫아도 안전합니다. Docker 앱은 계속 실행됩니다.

참고: 이 환경은 배포를 위해 최적화된 특수 compose 파일을 사용합니다. 더 많은 구성이 필요하다면 deploy-compose.yml 및 Dockerfile.multi 파일을 검토하여 설정 방법을 확인하시기 바랍니다. 이 환경은 RAM이 충분하지 않아 이미지를 직접 빌드하지 않습니다. 대신, main 브랜치에 푸시될 때마다 자동으로 빌드되는 최신 dev-api 이미지의 LibreChat을 가져옵니다.

LibreChat과 함께 사용할 도메인을 설정하는 경우, 이 compose 파일은 client/nginx.conf에 위치한 nginx 파일을 사용합니다. 이에 대한 지침은 아래 V부에서 확인하실 수 있습니다.

4. 앱이 실행되면 http://yourserverip에서 접속할 수 있습니다

Droplet 페이지로 돌아가 서버 IP를 확인하고, 이를 복사하여 브라우저에 붙여넣으세요!

회원가입 및 로그인 후, 직접 호스팅하는 나만의 원격 LibreChat을 즐겨보세요 :)

3부: LibreChat 업데이트하기

위의 모든 항목이 성공적으로 설치되었고 git 기록을 수정하지 않았다면, 이 단계는 매우 간편하게 진행할 수 있습니다.

참고: client/nginx.conf에 대한 수정 사항과 같이 본인만의 커밋이 포함된 편집된 브랜치에서 작업 중인 경우, config/deployed-update.js를 검토하여 필요에 따라 일부 명령어를 수동으로 실행해야 합니다. 이에 대한 자세한 내용은 V부를 참조하십시오.

자동 업데이트를 수행하려면 다음을 실행하세요

npm run update:deployed

Docker 컨테이너 중지하기

npm run stop:deployed

이는 단순히 docker compose -f ./deploy-compose.yml down을 실행합니다.

Docker 컨테이너 시작하기

npm run start:deployed

이것은 단순히 docker compose -f ./deploy-compose.yml up -d를 실행합니다.

활성 Docker 컨테이너 확인

docker ps

스크립트 사용 시 문제가 발생할 경우 수동으로 업데이트할 수 있습니다.

docker compose -f ./deploy-compose.yml down

# Linux/Mac
docker images -a | grep "librechat" | awk '{print $3}' | xargs docker rmi

# Windows (PowerShell)
docker images -a --filter "reference=registry.librechat.ai/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }
docker images -a --filter "reference=ghcr.io/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }

git pull

docker compose -f ./deploy-compose.yml pull

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

Part IV: NGINX 파일 편집 (사용자 지정 도메인 및 고급 설정용)

어떠한 이유로든 사용자 지정 도메인으로 서버를 연결하는 등 NGINX 파일을 수정해야 하는 경우, 다음을 사용하세요:

npm run stop:deployed

nano client/nginx.conf

사용자 지정 도메인 설정이나 NGINX에 대한 기타 변경 사항은 다루지 않겠습니다. 사용자 지정 도메인 설정을 시작하려면 Cloudflare 가이드, Traefik 가이드 또는 NGINX 가이드를 참조하시기 바랍니다.

하지만 이 설정으로 커스텀 도메인을 사용할 때 LibreChat 측에서 무엇을 수정해야 하는지 알려드리겠습니다.

NGINX가 기본적으로 proxy pass로 사용되고 있으므로, 다음 사항만 수정합니다:

# before
server_name localhost;

# after
server_name custom.domain.com;

참고: 이 설정은 메인 docker-compose.yml 파일과 달리 deploy-compose.yml 파일이 기본적으로 NGINX를 사용하기 때문에 작동합니다. 언제나 그렇듯, 필요에 따라 compose 파일을 구성할 수 있습니다.

이제 이 변경 사항을 별도의 브랜치에 커밋하세요:

# create a new branch
# example: git checkout -b edit
git checkout -b <branchname>

# stage all file changes
git add .

git 브랜치에 변경 사항을 커밋하려면 git에서 본인 확인을 해야 합니다. 이 값들은 가짜여도 상관없지만, LibreChat의 포크된 저장소로 이 브랜치를 푸시하여 GitHub와 동기화하고 싶다면 본인의 GitHub 이메일을 사용하세요.

# these values will work if you don't care what they are
git config --global user.email "[email protected]"
git config --global user.name "Your Name"

# Now you can commit the change
git commit -m "edited nginx.conf"

편집된 브랜치에서 업데이트하는 방식이 이제 약간 다르게 작동합니다.

npm run rebase:deployed

이제 모든 준비가 완료되었습니다!

경고 브랜치를 크게 수정하기 시작하면 병합 충돌이 발생할 수 있으며, 관련 내용을 잘 알고 있는 경우가 아니라면 권장되지 않습니다.

이 환경에서 코드에 변경 사항을 적용하더라도 GitHub에서 자동으로 빌드된 Docker 이미지를 compose 파일이 가져오기 때문에 해당 변경 사항은 반영되지 않는다는 점을 유의하세요.

5부: 최신 메인 브랜치 대신 최신 안정 릴리스 사용하기

기본적으로 이 설정은 LibreChat의 main 브랜치에 대한 최신 업데이트를 가져옵니다. latest tags로 정의된 최신 "stable" 릴리스를 사용하려면, deploy-compose.yml을 편집하고 5부에서와 같이 변경 사항을 커밋해야 합니다. 이렇게 하면 최신 기능을 즉시 사용할 수 없다는 점을 유의하십시오.

deploy-compose.yml 파일을 수정해 보겠습니다:

nano deploy-compose.yml

librechat-dev-api를 librechat-api로 변경하세요:

image: registry.librechat.ai/danny-avila/librechat-api:latest

5부에서와 같이 스테이징하고 커밋하면 모든 준비가 완료됩니다!