Xray Single Node Manual Docker Compose Installation

JFrog Installation & Setup Documentation
Content Type
Installation & Setup
ft:sourceType
Paligo

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

Xray System Requirements
Xray Node Recommendations

Use a dedicated node for Xray with no other software running to alleviate performance bottlenecks, avoid port conflicts, and avoid setting uncommon configurations.

Xray Storage Recommendations

In most cases, our recommendation is to use an SSD drive for Xray to have better performance and it is not recommended to use an NFS drive, as it is a disk I/O-intensive service, a slow NFS server can suffer from I/O bottlenecks and NFS is mostly used for storage replication.

Xray stores node-specific files, such as configuration and temporary files, to the disk. These files are exclusively used by Xray and not shared with other services. Since the local storage used for Xray services is temporary, it does not require replication between the different nodes in a multi-node/HA deployment.

Xray File Handle Allocation Limit

Use the following command to determine the current file handle allocation limit.

cat /proc/sys/fs/file-max

Then, set the following parameters in your /etc/security/limits.conf file to the lower of 100,000 or the file handle allocation limit determined above.

The example shows how the relevant parameters in the /etc/security/limits.conf file are set to 100000. The actual setting for your installation may be different depending file handle allocation limit in your system.

root hard nofile 100000
root soft nofile 100000
xray hard nofile 100000
xray soft nofile 100000
postgres hard nofile 100000
postgres soft nofile 100000
Operating Systems and Platform Support

The following table lists the supported operating systems and their versions:

Product

Debian

RHEL

Ubuntu

Amazon Linux

Windows Server

Xray

10.x, 11.x

8.x, 9.x

20.04, 22.04

Amazon Linux 2023

For more information about the supported operating systems for Insights and Pipelines, see Insights System Requirements and Pipelines System Requirements.

Note

Debian 12.x and Ubuntu 24.04 are supported from Artifactory 7.104.x and Distribution 2.28.

Supported Platforms

The following table lists the supported platforms:

Product

x86-64

ARM64

Kubernetes

OpenShift

Xray

1.27+

4.14+

For more information about the supported platforms for Insights and Pipelines, see Insights System Requirements and Pipelines System Requirements.

Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3+.

Kubernetes Sizing Requirements

We have included YAML files with different sizing configurations for Artifactory , Xray, and Distribution in our GitHub pages. You can use these YAML files when you set up your cluster.

ARM64 Support for Container-Based Installations

Starting from version 7.41.4, Artifactory supports installation on ARM64 architecture specifically through Helm and Docker installations. When deploying Artifactory on an ARM64 platform, an external database must be set up as Artifactory does not support the bundled database for ARM64 installations. The appropriate ARM64 Container Image is automatically pulled during the Helm or Docker installation process.

Additionally, ARM64 support is available for Xray and Distribution all through container-based Installations.

Database and Third-Party Applications in Xray

Every artifact and build indexed by Xray is broken down into multiple components. These components and the relationships between each other are represented in a checksum based components graph. Xray uses PostgreSQL to store and query this components graph.

Xray supports the following versions of PostgreSQL:

  • 16.x (from version 3.107)

  • 15.x (from version 3.78.9)

  • 14.x

  • 13.x (from version 3.18)

RabbitMQ is installed as part of the Xray installation for every node. In case of HA architecture, Xray uses queue mirroring between the different RabbitMQ nodes. External RabbitMQ instances are not officially supported; the recommended method of installation is to use the bundled RabbitMQ.

Xray has multiple flows, such as scanning, impact analysis, and database sync. These flows require processing completed by the different Xray microservices. Flows contain multiple steps that are completed by the Xray services. Xray uses RabbitMQ to manage these different flows and track synchronous and asynchronous communication between the microservices.

Xray also uses Erlang and DB-Util third-party applications. These packages are bundled with all Xray installers except Linux Archive. You need to use Erlang version 25.x and you can use the latest available version db-util.

Xray Network Ports

Xray uses the 8082 port by default for external communication.

Xray uses the following internal ports by default for communication with JFrog Platform microservices.

Microservice

Port

Xray Server

8000

Analysis

7000

Indexer

7002

Persist

7003

Router

HTTP: 8082, 8046, 8049

gRPC: 8047

RabbitMQ

4369, 5671, 5672, 15672, and 25672

PostgreSQL (if you use the bundled PostgreSQL database)

5432

Observability

HTTP: 8036

gRPC: 8037

In addition, review the Docker requirements.

Docker Requirements

For Docker and Docker Compose installations, JFrog services require Docker 20.10.10 and above, and Docker Compose v1.24 and above to be installed on the machine where you want to run them.

For more information, see Docker and Docker Compose.

Follow these steps to install the product:

  1. Extract the contents of the compressed archive and go to the extracted folder.

    tar -xvf jfrog-xray-<version>-compose.tar.gz

    .env file included within the Docker-Compose archive

    The .env file is used by docker-compose and is updated during installations and upgrades.

    Some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.

  2. Create the following folder structure under JFROG_HOME.

    |-- [         ]  app
    |-- [         ]  third-party
        |-- [999   999]  rabbitmq
|-- [1035 1035]  var
    |-- [1035 1035]  data
    |-- [1035 1035]  etc

  3. Copy the appropriate docker-compose templates from the templates folder to the extracted folder. Rename it as docker-compose.yaml.

    Requirement

    Template

    Xray

    docker-compose.yaml

    RabbitMQ

    docker-compose-rabbitmq.yaml

    PostgreSQL

    docker-compose-postgres.yaml

    Docker for Mac

    When you use Docker Compose in Mac, /etc/localtime might not work as expected since it might not be a shared location in the docker-for-mac settings.

    You can remove the following line from the selected docker-compose.yaml file to avoid installation issues.

    - /etc/localtime:/etc/localtime:ro

  4. Update the .env file.

    ## The installation directory for Xray. Default [$HOME/.jfrog/xray]
ROOT_DATA_DIR=
 
# Host ID. Other nodes in the cluster will use this ID to identify this node
HOST_ID=
 
# ID of the active node. Please leave the value as "None" for active nodes. (shared.rabbitMq.active.node.name). 
JF_SHARED_RABBITMQ_ACTIVE_NODE_NAME=None
 
# IP of the active node. (shared.rabbitMq.active.node.ip)
JF_SHARED_RABBITMQ_ACTIVE_NODE_IP=127.0.0.1
 
# Bind IP for Internal ports of Third party applications
JF_THIRD_PARTY_BIND_IP=127.0.0.1ROOT_DATA_DIR=

  5. Customize the product configuration.

    1. Set the Artifactory connection details.

    2. Customize the PostgreSQL Database connection details. (optional)

    3. Set any additional configurations (for example: ports, node id) using the Xray system.yaml file.

      Note

      Ensure the host's ID and IP are added to the system.yaml. This is important to ensure that other products and Platform deployments can reach this instance.

    4. Enter the RabbitMQ information in system.yaml. If you want to setup a RabbitMQ HA cluster, enter the information in all the slave nodes.

      shared:
  rabbitMq:
    active:
      node:
        ip: <IP>
        name: <xray-master-node-id>
# Enter the value of HOST_ID from the .env file as xray-master-node-id and the value of JF_THIRD_PARTY_BIND_IP value from the .env file as the IP.

  6. Customize any additional product configuration (optional) including, Java Opts and filestore.

  7. Copy the rabbitmq.conf and setRabbitCluster.sh files to the folder app/third-party/rabbitmq.

    Ensure both are owned by 999:999 (rabbitmq uid/gid)

  8. Edit rabbitmq.conf and enter the following information. If you want to setup a RabbitMQ HA cluster, enter the information in all the slave nodes.

    cluster_formation.peer_discovery_backend = rabbit_peer_discovery_classic_config
cluster_formation.classic_config.nodes.1 = rabbit@<xray-master-node-id># Enter the value of HOST_ID from the .env file as xray-master-node-id.

  9. Start Xray and PostgreSQL using docker-compose commands.

    ## Start RabbitMQ before starting other services

docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
   
## From Xray 3.8.x, Start PostgreSQL before starting the other services.

docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d
docker-compose -p xray up -d
  
## Check whether service is up

docker-compose -p xray psdocker-compose -p distribution logs
docker-compose -p distribution ps
docker-compose -p distribution up -d
docker-compose -p distribution down

  10. Access Artifactory from your browser at: http://SERVER_HOSTNAME/ui/.

    For example, on your local machine: http://localhost/ui/.

  11. Check the Xray log.

    docker-compose -p xray logs

    Configure log rotation of the console log

    The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.Configuring Log Rotation for Tomcat

Xray Product Configuration

After installing and before running Xray, you may set the following configurations.

You can configure all your system settings using the system.yaml file located in the $JFROG_HOME/xray /var/etc folder. For more information, see Xray System YAML.

If you don't have a System YAML file in your folder, copy the template available in the folder and name it system.yaml.

For the Helm charts, the system.yaml file is managed in the chart’s values.yaml.

Artifactory Connection Details for Xray

Xray requires a working Artifactory server and a suitable license. The Xray connection to Artifactory requires the following parameters.

  • jfrogUrl

    URL to the machine where JFrog Artifactory is deployed, or the load balancer pointing to it. It is recommended to use DNS names rather than direct IPs. For example: http://jfrog.acme.com or http://10.20.30.40:8082. Note that /artifactory context is not longer required.

    Set it in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yamlfile.

  • join.key

    This is the "secret" key required by Artifactory for registering and authenticating the Xray server.

    You can fetch the Artifactory joinKey (join Key) from the JPD UI in the User Management | Settings | Join Key.

    Set the join.key used by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

Change PostgreSQL database credentials

Xray comes bundled with a PostgreSQL database out-of-the-box, which come pre-configured with the default credentials.

To change the default credentials:

# Access PostgreSQL as the Xray user adding the optional -W flag to invoke the password prompt
$ psql -d xraydb -U xray -W
  
# Securely change the password for user "xray". Enter and then retype the password at the prompt.
\password xray
  
# Verify the update was successful by logging in with the new credentials
$ psql -d xraydb -U xray -W

Set your PostgreSQL connection details in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

Change RabbitMQ database credentials

Xray comes pre-installed with RabbitMQ, by setting the Erlang cookie value as the RabbitMQ password for guest users.

Docker Compose

  1. Set the new password in the <MOUNT_DIR>/app/third-party/rabbitmq/rabbitmq.conf file.

    default_pass = <new password>

  2. Set your RabbitMQ password in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

  3. Restart all services.

    cd jfrog-xray-<version>-compose   
docker-compose -p xray restart
Configure RabbitMQ to use FQDN for clustering

By default, RabbitMQ uses the short hostnames of other nodes in the cluster for communication. However, it be can be configured to use a fully qualified domain name (FQND) host name (a long hostname).

To configure RabbitMQ to use FQDN, follow these steps.

  1. Install Xray , but do not start the services.

  2. Modify the following files according to the installer type.

    • Docker-Compose

      In docker-compose-rabbitmq.yaml:
 
      environment:
      - RABBITMQ_USE_LONGNAME=true
 
In .env:
 
    HOST_ID=<long hostname>
    ## For secondary nodes only, provide the hostname of any of the active nodes where RabbitMQ service is running.
    #JF_SHARED_RABBITMQ_ACTIVE_NODE_NAME=<long hostname of active node>

    • Common Change in All Installers

      In system.yaml:
 
shared:
  node:
    id: <long hostname>
    name: <long hostname>
## For secondary nodes only, provide the hostname of any of the active nodes where RabbitMQ service is running.
#  shared:
#    rabbitMq:
#      active:
#        node:
#          name: <long hostname of active node>

  3. Start RabbitMQ and the Xray services.

Third Party Log Collector

Xray enables using an external log collector such as Sumologic or Splunk.

To adjust the permissions to allow the log collection service perform read operations on the generated log files.

  1. Add the log collection service user to the relevant group if needed (the user and group that installed and started Xray).

  2. Apply the user and group permissions as needed on the $JFROG_HOME/xray/var/log directory using:

    $ chmod -R 640 $JFROG_HOME/xray/var/log

  3. Adjust the group read inheritance permissions setgid bit using:

    $ chmod -R 2755 $JFROG_HOME/xray/var/log

    This command enables the generated log files to inherit the folder's group permissions.