본 가이드는 Docker Compose를 이용하여 JFrog Xray 및 RabbitMQ를 설치하고 구성하는 방법을 설명합니다.
설치환경
본 가이드는 다음 환경을 기준으로 작성되었습니다.
Docker : v26.1.3 Artifactory : 7.146.35 Xray : 3.137.36 RabbitMQ : 4.1.5 PostgreSQL : External PostgreSQL
Xray는 Artifactory와 연동하여 Artifact 및 Package에 대한 보안 취약점과 라이선스를 분석합니다.
Xray 구축 시 Artifactory를 먼저 구성한 후 RabbitMQ와 Xray를 순차적으로 구성합니다.
Docker 요구사항
Xray를 설치할 서버에 Docker 및 Docker Compose가 설치되어 있어야 합니다.
다음 명령을 사용하여 Docker가 정상적으로 설치되어 있는지 확인합니다.
docker --version docker compose version docker ps
오프라인 환경에서는 Xray 설치에 필요한 Docker Image 및 Docker Compose 설치 파일을 사전에 반입합니다.
설치 파일 다운로드
아래 링크에 접속하여 Docker Compose를 다운로드합니다.
https://jfrog.com/download-legacy/?product=xray
서버에서 받는 법
VERSION=[RELEASE]
curl -L -J -O \
"https://releases.jfrog.io/artifactory/jfrog-xray/xray-compose/${VERSION}/jfrog-xray-${VERSION}-compose.tar.gz"
Xray Release Notes
JFrog Home 환경 변수 설정
JFrog Xray 데이터를 저장할 기본 경로를 설정합니다.
export JFROG_HOME=/data/jfrog
Xray 디렉토리 설정
Xray 데이터를 저장할 디렉토리를 생성합니다.
mkdir -p $JFROG_HOME/xray chown -R 1030:1030 $JFROG_HOME chmod -R 755 $JFROG_HOME
본 가이드에서는 다음 경로를 Xray Installation Directory로 사용합니다.
/data/jfrog/xray
설치 스크립트를 이용하지 않는 경우 master.key 및 join.key를 수동으로 구성해야 하므로, 본 가이드에서는 설치 스크립트를 이용하여 설치합니다.
데이터베이스 연동
Xray에서 사용할 PostgreSQL 데이터베이스를 준비합니다.
Artifactory와 Xray는 각각 별도의 데이터베이스를 사용하도록 구성합니다.
Artifactory Database : artifactory Xray Database : xray
Xray 설치 전 다음 정보를 준비합니다.
Database Type : postgresql Database Host : <DB_HOST> Database Port : 5432 Database Name : xray Database Username : <XRAY_DB_USER> Database Password : <XRAY_DB_PASSWORD>
Xray 설치
설치 파일 준비
오프라인 환경에서는 사전에 반입한 Docker Image 및 Xray Docker Compose 설치 파일을 사용합니다.
구축 시 사용한 설치 파일은 다음과 같습니다.
jfrog-images-7.146.35-3.137.36.tar.gz jfrog-xray-3.137.36-compose.tar.gz
Docker Image를 Load합니다.
docker load -i jfrog-images-7.146.35-3.137.36.tar.gz
Xray Docker Compose 설치 파일의 압축을 해제합니다.
tar -xzf jfrog-xray-3.137.36-compose.tar.gz cd jfrog-xray-3.137.36-compose
configV2.sh 실행
Xray 설치 스크립트를 실행합니다.
sudo ./configV2.sh
설치 과정에서 설치할 Component를 선택합니다.
Please select the components to install: 1) Xray + RabbitMQ 2) Xray Only 3) RabbitMQ Only Enter your choice (1-3): 1
Xray와 RabbitMQ를 함께 구성하는 경우 1) Xray + RabbitMQ를 선택합니다.
설치 과정에 대한 로그는 config.log에 기록됩니다.
호스트 IP 설정
현재 Xray를 설치하는 서버의 IP 주소를 입력합니다.
Please specify the IP address of this machine (Default: ::1): <XRAY_HOST_IP>
HA 구성에서 추가 노드를 설치하는 경우 기존 Product Cluster에 추가되는 노드인지 선택합니다.
첫 번째 노드인 경우:
Are you adding an additional node to an existing product cluster? [y/N]: N
추가 노드인 경우:
Are you adding an additional node to an existing product cluster? [y/N]: y
설치 완료 후 생성된 system.yaml에서 Node 정보를 확인합니다.
cd $JFROG_HOME/xray/var/etc/ cp system.yaml system.yaml.bak vi system.yaml
예시는 다음과 같습니다.
shared:
node:
id: XRAY1
name: XRAY1
ip: <XRAY_HOST_IP>
HA 구성에서는 각 노드를 구분할 수 있도록 Node ID 및 Name을 고유하게 설정합니다.
PostgreSQL 설정
설치 과정에서 Xray가 사용할 Database Type을 선택합니다.
Enter database type, supported values [ postgresql mssql mariadb mysql oracle derby ]: postgresql
PostgreSQL URL을 입력합니다.
PostgreSQL url: jdbc:postgresql://<DB_HOST>:5432/xray
Database Username을 입력합니다.
Database username: <XRAY_DB_USER>
Database Password를 입력합니다.
Database password: <XRAY_DB_PASSWORD>
설치 스크립트에서는 Database Type, PostgreSQL URL, Username, Password 순으로 데이터베이스 정보를 입력합니다.
Xray 설정
설치 완료 후 생성된 system.yaml 파일을 확인합니다.
설정 변경 전 기존 파일을 백업합니다.
cd $JFROG_HOME/xray/var/etc/ cp system.yaml system.yaml.bak vi system.yaml
기본적인 Node 및 Database 구성은 다음과 같습니다.
shared:
node:
id: XRAY1
name: XRAY1
ip: <XRAY_HOST_IP>
database:
type: postgresql
driver: org.postgresql.Driver
url: <XRAY_DATABASE_URL>
username: <XRAY_DB_USER>
password: <XRAY_DB_PASSWORD>
환경에 맞게 Node 및 Database 정보를 설정합니다.
HA 환경에서는 각 Xray 노드를 구분할 수 있도록 Node ID 및 Name을 고유하게 설정합니다.
system.yaml에는 Database Password, Join Key 등의 중요 정보가 포함될 수 있으므로 외부 공유 시 실제 값을 노출하지 않도록 주의합니다.RabbitMQ 설정
Xray는 내부 서비스 간 메시지 처리를 위해 RabbitMQ를 사용합니다.
Xray와 RabbitMQ를 함께 설치하는 경우 configV2.sh를 통해 생성된 설정을 기준으로 RabbitMQ를 구성합니다.
HA 환경에서는 .env 파일에서 RabbitMQ Active Node 정보를 설정합니다.
vi .env
다음 값을 환경에 맞게 설정합니다.
JF_SHARED_RABBITMQ_ACTIVE_NODE_NAME=<RABBITMQ_NODE_HOSTNAME> JF_SHARED_RABBITMQ_ACTIVE_NODE_IP=<RABBITMQ_NODE_IP>
Xray Router 포트 설정
Artifactory와 Xray가 동일한 서버에서 실행되는 경우 Router Port가 충돌하지 않도록 설정해야 합니다.
본 구축 환경에서는 Artifactory Router가 8082 포트를 사용하므로 Xray Router의 External Port를 8083으로 구성하였습니다.
.env 파일을 수정합니다.
vi .env
다음 값을 설정합니다.
JF_ROUTER_ENTRYPOINTS_EXTERNALPORT=8083
Xray 실행
Xray를 실행하기 전에 RabbitMQ를 먼저 실행합니다.
RabbitMQ를 실행합니다.
docker compose -f docker-compose-rabbitmq.yaml up -d
RabbitMQ가 정상적으로 실행되었는지 확인합니다.
docker logs -f xray_rabbitmq
RabbitMQ가 정상적으로 기동된 것을 확인한 후 Xray를 실행합니다.
docker compose -p rt up -d
구축 시에도 RabbitMQ를 먼저 실행한 후 Xray를 실행하는 순서로 구성하였습니다.
Xray 관리
실행 중인 Container를 확인합니다.
docker ps
Xray를 중지합니다.
docker compose -p rt down
Xray를 실행합니다.
docker compose -p rt up -d
RabbitMQ를 중지합니다.
docker compose -f docker-compose-rabbitmq.yaml down
RabbitMQ를 실행합니다.
docker compose -f docker-compose-rabbitmq.yaml up -d
재기동 시 RabbitMQ가 정상적으로 기동된 것을 확인한 후 Xray를 실행합니다.
Xray 로그 및 상태 확인
Container 상태 확인
다음 명령을 사용하여 Xray Container의 실행 상태를 확인합니다.
docker ps
정상적으로 기동된 경우 다음과 같은 Xray 관련 Container를 확인할 수 있습니다.
xray_server xray_indexer xray_sbom xray_policyenforcer xray_persist xray_analysis xray_router xray_rabbitmq
실제 구축 환경에서도 Server, Indexer, SBOM, Policy Enforcer, Persist, Analysis, Router 및 RabbitMQ가 각각 Container로 기동되는 것을 확인할 수 있습니다.
로그 확인
RabbitMQ 로그를 확인합니다.
docker logs -f xray_rabbitmq
Xray 전체 기동 상태는 Router 로그를 통해 확인합니다.
docker logs -f xray_router
Xray 서비스 기동 중 오류가 발생하는 경우 Server 로그를 추가로 확인합니다.
docker logs -f xray_server
Xray는 여러 서비스로 구성되어 있으므로 xray_router를 통해 전체 기동 상태를 확인하고, 오류 발생 시 해당 서비스의 로그를 추가로 확인합니다.
Health Check
다음 명령을 사용하여 Xray Router 및 내부 서비스의 상태를 확인합니다.
curl -sS http://127.0.0.1:8083/router/api/v1/system/health
정상적으로 기동된 경우 Router 및 각 Xray Service의 state가 HEALTHY로 표시됩니다.
{
"router": {
"node_id": "XRAY1",
"state": "HEALTHY",
"message": "OK"
}
}
Router가 정상적으로 기동되지 않거나 특정 서비스가 HEALTHY 상태가 아닌 경우 관련 로그를 확인합니다.
docker logs -f xray_router docker logs -f xray_server
RabbitMQ 관련 문제가 의심되는 경우 RabbitMQ 로그를 확인합니다.
docker logs -f xray_rabbitmq