Docker를 사용하여 Onyx를 설치하는 완벽 가이드

Onyx는 언어 모델을 문서, 애플리케이션 및 지식 기반과 연결하도록 설계된 오픈 소스 AI 플랫폼입니다. 팀 채팅, 기업 검색 엔진, RAG 시스템, 에이전트 및 도구를 갖춘 작업 공간으로 활용할 수 있습니다.

이 플랫폼은 관리형 서비스로 계약할 수도 있지만, 자체 인프라에 배포할 수도 있습니다. 후자의 경우, Docker Compose는 가장 접근하기 쉬운 방법 중 하나입니다.인터페이스, API, 데이터베이스, 인덱싱 프로세스 및 기타 구성 요소를 모든 종속성을 수동으로 설치하지 않고도 실행할 수 있기 때문입니다.

이 가이드에서는 Docker를 사용하여 Onyx를 설치하는 방법, Lite 모드와 Standard 모드의 차이점, 컨테이너 관리 방법, 그리고 인스턴스를 인터넷에 게시하기 전에 수행해야 할 단계를 살펴보겠습니다.

Onyx는 무엇이며 어떤 서비스와 연결할 수 있습니까?

Onyx는 인공지능 모델을 사용하여 문서와 애플리케이션에서 정보를 검색할 수 있는 기업용 채팅 및 검색 플랫폼입니다. 상용 공급업체는 물론 자체 인프라에 호스팅된 모델과도 연결할 수 있습니다.

주요 기능은 다음과 같습니다.

• 다양한 업체 소속 모델들과 채팅하세요.
• 행동을 수행할 수 있는 에이전트 및 도구.
• 지식 소스를 동기화하는 커넥터.
• 키워드와 벡터를 활용한 하이브리드 검색.
• RAG의 답변은 문서에 기반합니다.
• 심층 조사 및 웹 검색.
• 액션 및 MCP를 통한 도구와의 통합.
• 파일 업로드 및 프로젝트별 정리.
• 사용자 관리 및 인증 시스템.

Onyx에는 사용하려는 생성 모델이 포함되어 있지 않을 수 있습니다. 설치 후 OpenAI, Anthropic, Gemini, Ollama, LiteLLM 또는 vLLM과 같은 제공업체를 구성해야 합니다.

Onyx Lite 또는 Standard: 어떤 버전을 설치해야 할까요?

현재 설치 프로그램에서는 두 가지 모드 중 하나를 선택할 수 있습니다. 각 모드는 서로 다른 아키텍처와 기능 세트를 배포하므로 선택은 중요합니다.

특징	오닉스 라이트	오닉스 스탠다드
모델과 채팅하기	응	응
에이전트 및 도구	응	응
파일 업로드	응	응
프로젝트	응	응
외부 소스가 있는 커넥터	아니요	응
RAG 인덱싱 및 검색	아니요	응
오픈서치	아니요	응
레디스	아니요	응
인덱싱용 모델 서버	아니요	응
백그라운드 프로세스	API에 통합됨	독립형 컨테이너
권장 사용법	테스트, 채팅 및 소규모 팀	RAG, 커넥터 및 조직

오닉스 라이트 이 옵션은 플랫폼 테스트, 채팅 기능 사용 또는 리소스가 제한된 서버에서 작업하는 데 가장 적합합니다. 파일, 캐시 및 세션은 PostgreSQL에 저장되며 전체 검색 인프라는 실행하지 않습니다.

오닉스 스탠다드 이 시스템은 커넥터를 사용하고, 문서를 동기화하며, 엔터프라이즈 검색 시스템을 구축하도록 설계되었습니다. OpenSearch, Redis, 백그라운드 프로세스, 객체 스토리지 및 인덱싱에 사용되는 서버가 추가되므로 훨씬 더 많은 메모리와 저장 공간이 필요합니다.

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

Onyx는 Docker를 사용하여 Linux, macOS 또는 Windows에서 실행할 수 있습니다. 프로덕션 서버의 경우 최신 Linux 배포판을 사용하는 것이 일반적으로 더 좋습니다.

공식적인 요구 사항은 선택한 모드에 따라 다릅니다.

방법	최소 CPU	최소 RAM 용량	최소 디스크 공간	선호하는 구성
오닉스 라이트	2 vCPU	2GB	10GB	4개의 vCPU, 4GB의 RAM 및 50GB
오닉스 스탠다드	4 vCPU	10GB	32GB에 색인 데이터 저장 공간이 추가됩니다.	8개 이상의 vCPU와 16GB 이상의 RAM

표준 모드에서는 문서에서 색인된 문서의 크기를 예상하고 여유분을 충분히 두도록 권장합니다. 실제 리소스 사용량은 콘텐츠 양, 임베딩, 동시 접속 수 및 OpenSearch 구성에 따라 달라집니다.

시작하기 전에 다음이 필요합니다.

• 서버를 관리할 수 있는 권한이 있는 계정.
• Docker Engine과 Docker Compose 플러그인.
• 이미지와 모델을 다운로드하려면 인터넷 연결이 필요합니다.
• 수동으로 설치할 경우 Git을 사용하세요.
• 파이썬과 uv Onyx CLI를 직접 설치하려면 다음을 참고하세요.
• 애플리케이션을 게시하려면 도메인과 해당 DNS 설정에 대한 액세스 권한이 필요합니다.

Docker 및 Compose를 확인하려면 다음 명령어를 사용하세요.

docker --version
docker compose version

리눅스에서는 사용자가 Docker를 실행하거나 사용할 수 있는지 여부도 확인해야 합니다. sudo 필요할 경우.

권장 설치 프로그램을 사용하여 Onyx를 설치하는 방법

현재 권장되는 방법은 제품에 포함된 안내 설치 프로그램을 사용하는 것입니다. 오닉스 CLI이 과정은 컴퓨터의 리소스를 확인하고, Lite 버전과 Standard 버전 중에서 선택할 수 있도록 하며, 이미지를 다운로드하고, 컨테이너를 시작하고, 모든 서비스가 사용 가능해질 때까지 기다립니다.

이미 설치되어 있는 경우 uv, 운영:

uv tool install onyx-cli
onyx-cli deploy install

담당자가 다음과 같이 질문할 것입니다.

• 라이트 모드와 스탠다드 모드 중 어떤 모드를 설치하시겠습니까?
• 어떤 버전의 Onyx를 배포하시겠습니까?
• 해당 환경은 어떤 구성을 사용해야 할까요?

새 설치 시 배포 파일은 다음 위치에 저장됩니다.

~/.config/onyx

이 디렉터리에는 스택 관리에 사용되는 구성 파일이 포함되어 있습니다. 다른 디렉터리와 혼동하지 마십시오. onyx_data이 폴더는 이전 버전의 설치 프로그램에서 생성된 것입니다. Onyx CLI는 이러한 이전 배포를 감지하고 사용할 수 있지만, 더 이상 새 설치의 기본 경로는 아닙니다.

공식 스크립트를 사용하여 Onyx를 설치하는 방법

공식 페이지에 게시된 명령어를 사용하셔도 됩니다.

curl -fsSL https://onyx.app/install_onyx.sh | bash

이 스크립트는 Onyx CLI 설치 프로그램의 래퍼입니다. 따라서 동일한 유형의 안내식 배포를 제공하며 더 이상 독립형 시스템으로 설명해서는 안 됩니다.

인터넷에서 다운로드한 스크립트를 바로 실행하기 전에 저장하고 내용을 검토할 수 있습니다.

curl -fsSLo install_onyx.sh https://onyx.app/install_onyx.sh
less install_onyx.sh
bash install_onyx.sh

설치 프로그램은 환경을 확인하고, 필요한 경우 호환되는 Linux 시스템에 Docker를 설치한 다음, 컨테이너가 정상적으로 작동할 때까지 기다립니다.

완료되면 접속 가능한 주소가 표시됩니다. 도메인에 연결하지 않은 로컬 설치의 경우 일반적으로 다음과 같습니다.

http://localhost:3000

Onyx가 네트워크상의 다른 서버에서 실행 중인 경우, 해당 서버를 대체합니다. localhost 해당 IP 주소를 통해 접근하십시오. 인증 및 HTTPS를 구성하지 않고 포트를 공개적으로 노출하지 마십시오.

Docker Compose를 사용하여 Onyx를 수동으로 설치하는 방법

수동 설치는 Compose 파일을 직접 검토하거나 Onyx를 자체 배포 파이프라인에 통합하려는 경우에 유용합니다. 하지만 업데이트 및 구성 변경을 직접 관리해야 합니다.

먼저 공식 저장소를 복제하세요.

git clone --depth 1 https://github.com/onyx-dot-app/onyx.git
cd onyx/deployment/docker_compose

게시된 이미지를 사용하여 표준 배포를 시작하려면 다음 단계를 따르세요.

docker compose up -d

소스 코드에서 이미지를 컴파일하려면 다음 단계를 따르세요.

docker compose up -d --build --force-recreate

코드를 직접 컴파일하는 것은 더 많은 시간과 리소스를 소모합니다. 일반적인 설치의 경우, 이미 공개된 공식 이미지를 사용하는 것이 더 좋습니다.

컨테이너를 시작한 후 Onyx는 준비 프로세스를 완료해야 합니다. 다음 명령으로 상태를 확인하세요.

docker compose ps

기록을 추적하려면:

docker compose logs -f

모든 서비스가 준비되면 시작하세요.

http://localhost:3000

Onyx Lite를 수동으로 배포하는 방법

Onyx Lite는 불필요한 서비스를 비활성화하는 추가 Compose 파일을 통해 활성화됩니다.

docker compose \
  -f docker-compose.yml \
  -f docker-compose.onyx-lite.yml \
  up -d

이 모드에서는 필수 서비스만 시작합니다.

• api_server또한 백그라운드 작업도 관리합니다.
• web_server인터페이스에 해당합니다.
• relational_dbPostgreSQL 기반입니다.
• nginx이는 역방향 프록시 역할을 합니다.

Lite 버전에는 커넥터, OpenSearch 또는 동기화된 소스에 대한 RAG 검색 기능이 포함되어 있지 않습니다. 파일을 업로드하고 프로젝트를 사용할 수는 있지만, 외부 애플리케이션의 문서를 색인화해야 하는 경우에는 표준 배포 버전을 대체할 수 없습니다.

Onyx Standard는 어떤 서비스를 이용하나요?

정확한 아키텍처는 버전 간에 변경될 수 있으므로 이전 Compose 파일을 복사하거나 PostgreSQL, Redis 또는 기타 구성 요소의 이미지를 수동으로 수정하는 것은 권장되지 않습니다.

일반적으로 Onyx Standard에는 다음이 포함됩니다.

• 주요 로직을 포함하는 API 서버입니다.
• 웹 인터페이스.
• PostgreSQL은 관계형 데이터베이스입니다.
• 커넥터 및 인덱싱을 위한 백그라운드 프로세스.
• 캐싱 및 세션 관리를 위해 Redis를 사용합니다.
• 벡터 및 키워드 검색을 위한 OpenSearch를 이용하세요.
• 색인 및 검색 중에 사용되는 모델 서버.
• MinIO 또는 호환 가능한 백엔드를 사용한 객체 스토리지.
• Nginx를 리버스 프록시로 사용합니다.

Onyx를 설치할 때 사용하는 버전에 포함된 파일을 항상 사용하십시오. 데이터베이스 버전을 개별적으로 변경하면 호환성 문제나 마이그레이션 실패가 발생할 수 있습니다.

초기 설정 완료 방법

새로운 서버에 처음 등록하는 사용자가 관리자가 됩니다. 따라서 다른 사용자가 서버에 접속하기 전에 이 단계를 완료해야 합니다.

로그인 후:

1. 관리자 계정에 강력한 비밀번호를 설정하세요.
2. 관리자 패널에 접속하세요.
3. 언어 모델 제공자를 구성합니다.
4. 해당 자격 증명을 추가하십시오.
5. 기본 모델을 선택하세요.
6. 테스트 대화를 진행하세요.
7. Standard 버전을 사용 중인 경우 커넥터를 생성하고 인덱싱을 확인하십시오.

Onyx는 상용 서비스 및 Ollama, vLLM, LiteLLM과 같은 자체 서버와 연동하여 사용할 수 있습니다. Onyx 자체 호스팅을 사용한다고 해서 모델이 자동으로 로컬에 저장되는 것은 아닙니다. OpenAI, Anthropic 또는 Gemini를 구성하는 경우 필요한 요청은 해당 제공업체로 전송됩니다.

CLI를 사용하여 Onyx를 관리하는 방법

현재 설치 프로그램의 장점 중 하나는 전체 배포 수명 주기를 관리하는 데 필요한 특정 명령어를 제공한다는 것입니다.

onyx-cli deploy status
onyx-cli deploy logs
onyx-cli deploy stop
onyx-cli deploy upgrade

주요 기능은 다음과 같습니다.

• status서비스 상태를 확인하세요.
• logs배포 로그를 표시합니다.
• stop컨테이너를 제거하지 않고 중지합니다.
• upgrade: 관리형 설치를 업데이트합니다.
• uninstall배포를 없애줍니다.

뛰지 마세요 uninstall 일시적인 오류를 해결하려면 삭제하기 전에 보존할 데이터와 볼륨을 확인하고 별도의 백업을 수행하십시오.

수동 설치를 업데이트하는 방법

Docker Compose 파일을 직접 관리하는 경우, 업데이트하기 전에 새 버전의 릴리스 노트를 검토하십시오. 그런 다음 저장소에서 변경 사항과 해당 이미지를 다운로드하십시오.

배포 디렉터리에서 일반적인 프로세스는 다음과 같습니다.

git pull
docker compose pull
docker compose up -d

테스트 없이 새 버전을 프로덕션 환경에 자동으로 배포하지 마십시오. 일부 업데이트에는 데이터베이스 마이그레이션, 환경 변수 변경 또는 서비스 수정이 포함될 수 있습니다.

Onyx CLI를 사용하여 설치한 경우 다음 명령어를 사용하는 것이 좋습니다.

onyx-cli deploy upgrade

지속성 및 백업

Docker Compose는 컨테이너를 다시 생성한 후에도 데이터베이스, 인덱스, 파일 및 기타 데이터를 보존하기 위해 볼륨을 사용합니다. 그러나 영구 볼륨은 백업과 동일하지 않습니다..

배포를 업데이트하거나 수정하기 전에:

• 저장된 설정을 복사하세요. ~/.config/onyx.
• 설치된 버전에 맞는 도구를 사용하여 PostgreSQL을 백업하십시오.
• 파일이나 객체 저장소에서 백엔드 데이터를 보존합니다.
• 서비스 복구에 필요한 환경 변수와 비밀 키를 저장합니다.
• 주기적으로 백업 복원이 가능한지 확인하십시오.
• 메인 서버와는 별도로 최소 한 개의 사본을 저장해 두십시오.

연결된 일부 소스는 다시 색인을 생성할 수 있지만, 데이터베이스에는 사용자, 설정, 대화 및 기타 데이터가 포함되어 있으므로 백업 없이는 복구할 수 없습니다.

도메인 및 HTTPS 설정 방법

Onyx를 인터넷에서 접속 가능하게 하려면 DNS 레코드가 서버의 공용 IP 주소를 가리키도록 도메인을 구성하십시오. 그런 다음 변수를 설정하십시오.

WEB_DOMAIN=onyx.ejemplo.com

해당 저장소에는 Docker 배포 환경에서 Let's Encrypt 인증서를 발급받는 스크립트가 포함되어 있습니다.

./init-letsencrypt.sh

실행하기 전에 환경 변수를 확인하고 도메인이 서버로 올바르게 연결되는지 확인하십시오. 또한 80번 포트와 443번 포트가 사용 가능해야 합니다.

다음과 같은 주소를 사용하여 프로덕션 인스턴스를 직접 게시하지 마십시오. http://IP:3000HTTPS를 사용하지 않으면 자격 증명과 데이터가 전송 중에 노출될 수 있습니다.

Onyx를 게시하기 전에 보호하는 방법

이메일과 비밀번호를 통한 인증이 기본적으로 활성화되어 있습니다. 최초로 등록된 계정에는 관리자 권한이 부여됩니다.

팀에서 사용하는 설치 환경의 경우:

• 관리자 계정을 즉시 등록하세요.
• 고유하고 강력한 비밀번호를 사용하세요.
• 방화벽을 사용하여 접근을 제한하십시오.
• 외부 연결을 허용하기 전에 HTTPS를 활성화하십시오.
• 필요에 따라 OAuth, OIDC 또는 SAML을 구성하십시오.
• 허용되는 이메일 도메인을 제한하세요.
• 더 이상 필요하지 않을 때는 열려 있는 로그를 비활성화하십시오.
• 모델 및 커넥터 공급업체의 키를 보호하십시오.
• Onyx, Docker 및 운영 체제를 업데이트하세요.
• MCP 에이전트, 작업 및 도구에 대한 권한을 검토하십시오.

최신 버전에서는 관리자 패널에서 일부 보안 설정을 구성할 수 있습니다. 기업 환경에서는 RBAC, 권한 동기화 또는 추가 비밀 키 암호화와 같은 고급 기능을 사용하려면 엔터프라이즈 에디션이 필요할 수 있습니다.

저장 공간 사용량을 모니터링하는 방법

표준 모드에서 OpenSearch는 검색에 사용되는 인덱스를 저장합니다. 디스크 사용량이 임계치(기본값 95%)에 도달하면 OpenSearch는 인덱스를 읽기 전용으로 표시하고 쓰기를 중지할 수 있습니다.

사용 가능한 공간을 주기적으로 확인하세요:

df -h
docker system df

볼륨 크기를 확인하고 더 이상 사용하지 않는 Docker 이미지를 삭제할 수도 있습니다.

docker image prune

이 명령은 남아있는 이미지를 제거하지만, 제거될 항목을 항상 검토해야 합니다. 영향을 받는 컨테이너, 이미지 및 볼륨을 먼저 확인하지 않고 프로덕션 서버에서 강력한 Docker 정리 명령을 사용하지 마십시오.

Plesk에서 Onyx를 설치할 수 있나요?

Plesk를 사용하면 개별 컨테이너를 생성하고 관리할 수 있지만, Onyx는 다양한 서비스, 네트워크, 종속성 및 볼륨으로 구성된 스택입니다. Plesk 인터페이스에서 컨테이너별로 Onyx를 재구축하는 것은 오류 발생 가능성이 높고 업데이트를 어렵게 만듭니다.

서버에서 Plesk를 사용하는 경우 다음 방법을 권장합니다.

1. SSH를 사용하여 서버에 접속하세요.
2. Docker와 Docker Compose가 사용 가능한지 확인하십시오.
3. Onyx CLI 또는 공식 Compose 파일을 사용하여 Onyx를 설치하세요.
4. Plesk는 도메인, DNS 또는 프록시 용도로 사용할 때는 두 시스템을 제대로 통합하는 방법을 알고 있는 경우에만 사용하십시오.

이 조합을 사용하기 전에 서버 제공업체가 Docker 관리를 허용하는지, 그리고 포트, 네트워크 및 리소스가 Plesk에서 관리하는 다른 서비스와 충돌하지 않는지 확인하십시오.

Docker를 사용하여 Onyx를 설치할 때 흔히 발생하는 오류

컨테이너는 아직 이용 가능하지 않습니다.

상태 및 기록을 확인하세요:

onyx-cli deploy status
onyx-cli deploy logs

수동 설치의 경우 다음을 사용하십시오.

docker compose ps
docker compose logs --tail=200

가장 흔한 원인은 메모리 부족, 저장 공간 부족, Docker 권한 문제 또는 시작이 완료되지 않은 종속 서비스입니다.

3000번 항구는 이미 점유 중입니다.

어떤 프로세스가 해당 포트를 사용하고 있는지 확인하거나 Compose 구성에서 포트 매핑을 수정하세요. 프록시 및 프록시에 의존하는 변수를 확인하지 않고 컨테이너의 포트만 변경하지 마십시오.

Onyx Lite에는 커넥터가 표시되지 않습니다.

이는 오류가 아닙니다. Lite 버전은 리소스 사용량을 줄이기 위해 커넥터, OpenSearch 및 RAG 검색 기능을 비활성화합니다. 외부 소스를 동기화하려면 Standard 버전을 사용하십시오.

OpenSearch에서 쓰기 작업을 더 이상 수락하지 않습니다.

사용 가능한 공간을 확인하십시오. 디스크 공간이 임계점에 도달한 경우, 먼저 저장 공간을 확보하거나 확장하십시오. 그런 다음 읽기 전용 잠금을 해제하기 전에 OpenSearch 설명서를 검토하십시오.

인터페이스는 열리지만 채팅이 응답하지 않습니다.

관리자 패널에서 유효한 공급자와 모델이 설정되어 있는지 확인하십시오. 또한 잔액, API 키 및 공급자와의 연결 상태를 확인하십시오.

서버 메모리가 부족합니다

올바른 모드를 선택했는지 다시 한번 확인하십시오. 소규모 서버의 경우 Lite 모드를 사용하십시오. Standard 모드는 최소 10GB의 RAM이 필요하며, 색인된 문서 수가 증가함에 따라 훨씬 더 많은 RAM이 필요할 수 있습니다.

업데이트로 인해 서비스 간 호환성 문제가 발생했습니다.

릴리스 노트, 마이그레이션 및 환경 파일을 검토하십시오. 안내 설치 프로그램을 사용한 경우 수동 명령과 혼합하지 말고 Onyx CLI를 사용하여 업그레이드를 관리하십시오.

Docker를 사용하여 Onyx를 설치하면 조직의 문서 및 애플리케이션에 연결된 AI 환경을 배포할 수 있습니다. 채팅 및 에이전트 테스트를 위해 Onyx Lite는 간단하고 저전력 아키텍처를 제공합니다. 외부 소스를 인덱싱하고 RAG 검색을 사용하려면 표준 배포를 선택하고 충분한 리소스를 할당해야 합니다.

Onyx CLI를 사용하면 설치, 로그, 상태 및 업데이트를 관리할 수 있으므로 설치를 유지 관리하는 가장 쉬운 방법은 Onyx CLI를 사용하는 것입니다. 운영 환경에서는 인증, HTTPS, 백업 및 스토리지 모니터링도 구성해야 합니다.