Installing Xray

Single Node Installation

The following installation methods are supported:

• Interactive Script (recommended)
• Manual Linux Archive
• Manual RPM
• Manual Debian
• Helm

Interactive Script Installation (recommended)

The installer script works with all supported upgrade methods (Linux Archive, RPM, Debian and Docker Compose). It provides you an interactive way to install Xray and its dependencies.

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

   tar -xvf jfrog-xray-<version>-<compose|rpm|deb>.tar.gz
   cd jfrog-xray-<version>-<compose|rpm|deb>

   OS user permissions for Linux archive

   When running Xray, the installation script creates a user called xray by default which must have run and execute permissions on the installation directory.

   It is recommended to extract the Xray download file into a directory that gives run and execute permissions to all users such as /opt.

   Linux archive

   mv jfrog-xray-<version>-linux.tar.gz /opt/
   cd /opt
   tar -xf jfrog-xray-<version>-linux.tar.gz
   mv jfrog-xray-<version>-linux xray
   cd xray

   .env file included within the Docker-Compose archive

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

   Notice that 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. Run the installer script.
   

   The script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey

   RPM or Debian

   ./install.sh

   Docker Compose

   ./config.sh

   Prerequisites for Linux archive

   Refer prerequisites for Xray in Linux Archive  before running install script.

   Linux archive

   ./install.sh --user <user name> --group <group name>
   
   -h | --help                                       : [optional] display usage
   -u | --user                                       : [optional] (default: xray) user which will be used to run the product, it will be created if its unavailable
   -g | --group                                      : [optional] (default: xray) group which will be used to run the product, it will be created if its unavailable

3. Validate and customize the product configuration(optional), including the third party dependencies connection details and ports.

   Verify that a large file handle limit is specified before you start Xray. 

4. Start and manage the Xray service.

   systemd OS

   systemctl start|stop xray.service

   Starting from Xray 3.8x, the stop and restart action on Xray will not be applied to RabbitMQ process. On start action of Xray, if RabbitMQ is not running, it will be started.

   If you want the script to perform stop and restart action on RabbitMQ, set shared.rabbitMq.autoStop as true in the system.yaml. Note that this flag is not consumed in docker-compose installation.

   systemv

   service xray start|stop

   Docker Compose

   cd jfrog-xray-<version>-compose
   
   # Starting from Xray 3.8x RabbitMQ has been moved to a compose file of its own, this needs to be started before starting other services
   docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
   
   # Starting from 3.8.x, PostgreSQL needs to be started before starting the other services.
   docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d
   
   docker-compose -p xray up -d
   
   docker-compose -p xray ps
   docker-compose -p xray down

   Xray can be installed and managed as a service in a Linux archive installation. Refer start Xray section under Linux Archive Manual Installation for more details. 

   Linux archive

   xray/app/bin/xray.sh start|stop

5. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI.

6. Check the Xray log.
   

   tail -f $JFROG_HOME/xray/var/log/console.log

   Configuring the Log Rotation of the Console Log

   The console.log file can grow quickly since all services write to it. This file is not log-rotated for Darwin installations. Learn more on how to configure the log rotation.

Manual Linux Archive Installation

Prerequisites

The following prerequisites must be installed independently of the Xray archive installation.  Make sure to install them before staring your Xray service.

• PostgreSQL

• Erlang - Packaged as RPM (or DEB) within the archive.

• Db-Utils - Packaged as RPM (or DEB) within the archive.

Install Steps

1. Extract the contents of the compressed archive and move it into xray directory.

   tar -xvf jfrog-xray-<version>-linux.tar.gz
   mv jfrog-xray-<version>-linux xray

   PostgreSQL is required and must be installed before continuing with the next installation steps.

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

2. Start PostgreSQL.

3. 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 configuration file.

4. Start and manage the Xray service as the user who extracted the tar.
   As a process

   Daemon Process

   xray/app/bin/xray.sh start

   Manage the process.

   xray/app/bin/xray.sh start|stop|status|restart

   As a service

   Xray is packaged as an archive file and an install script that can be used to install it as a service running under a custom user. Currently supported on Linux systems.

   OS User Permissions

   When running Xray as a service, the installation script creates a user called xray (by default) which must have run and execute permissions on the installation directory.

   It is recommended to extract the Xray download file into a directory that gives run and execute permissions to all users such as /opt.

   To install Xray as a service, execute the following command as root: 

   User and group can be passed through xray/var/etc/system.yaml as shared.user and shared.group. This takes precedence over values passed through command line on install. 

   xray/app/bin/installService.sh --user <enter user, default value is xray> --group <enter group, default value is xray>
   
   -u | --user                                       : [optional] (default: xray) user which will be used to run the product, it will be created if its unavailable
   -g | --group                                      : [optional] (default: xray) group which will be used to run the product, it will be created if its unavailable

   The user and group will be stored in xray/var/etc/system.yaml at the end of installation.

   To manage the service, use systemd or init.d commands depending on your system. 

   Using systemd

    systemctl <start|stop|status> xray.service

   Using init.d

   service xray <start|stop|status>

5. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Dashboard tab in the Application module in the UI.

6. Check Xray Log.
   

   tail -f xray/var/log/console.log

Manual RPM Installation

The RPM installation bundles Xray and all its dependencies. It is provided as native RPM packages, where Xray and its dependencies must be installed separately. Use this, if you are automating installations.

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

   tar -xvf jfrog-xray-<version>-rpm.tar.gz
   cd jfrog-xray-<version>-rpm

2. Install PostgreSQL. You can choose to install any compatible PostgreSQL version, or use the PostgreSQL RPM bundled with the Xray installer located under /third-party/postgresql.
   

   PostgreSQL is required and must be installed before continuing with the next installation steps.

   For a manually installed PostgreSQL, you need to set the database connection details in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.

3. Install db-util. You can use the bundled db-utils RPM found under /third-party/misc/.
   

   # This will install db-util if db_dump is not available
   hash db_dump 2>/dev/null || rpm -ivh --replacepkgs ./third-party/misc/<db-utils version>.x86_64.rpm

4. Install RabbitMQ dependencies.

   # Note : Use rpms with el7 when installing on Centos 7 and RHEL 7, and el8 with CentOS 8 and RHEL8. 
   Run the following from the extracted folder.
   rpm -ivh --replacepkgs ./third-party/rabbitmq/socat-<version>.x86_64.rpm
   rpm -ivh --replacepkgs ./third-party/rabbitmq/erlang-<version>.x86_64.rpm

5. Install Xray. You must run as a root user.

   rpm -Uvh --replacepkgs ./xray/xray.rpm

6. 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 configuration file.
      

      Verify that a large file handle limit is specified before you start Xray. 

7. Start and manage the Xray service.
   

   systemd OS

   systemctl start|stop xray.service

   systemv OS

   service xray start|stop|status|restart

8. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

9. Check the Xray Log.
   

   Linux

   tail -f $JFROG_HOME/xray/var/log/console.log

Manual Debian Installation

The Debian installation bundles Xray and all its dependencies. It is provided as native Debian packages, where Xray and its dependencies must be installed separately. Use this, if you are automating installations.

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

   tar -xvf jfrog-xray-<version>-deb.tar.gz
   cd jfrog-xray-<version>-deb

2. Install PostgreSQL.
   

   PostgreSQL is required and must be installed before continuing with the next installation steps.
   

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

3. Install db-util.
   

   db-util allows us to interact with the Berkley DB that contains information about RPM-based Docker images. This way, JFrog Xray can index OS packages for these images.

   Ubuntu

   dpkg -i ./third-party/misc/db5.<version>.deb
   dpkg -i ./third-party/misc/db-util_<version>.deb

   Debian 8

   dpkg -i ./third-party/misc/db5.<version>.deb
   dpkg -i ./third-party/misc/db-util_<version>.deb

   Debian 9

   dpkg -i ./third-party/misc/db5.<version>.deb
   dpkg -i ./third-party/misc/db-util_<version>_all.deb

4. Install RabbitMQ dependencies.
   

   ubuntu 16.04 (xenial)

   dpkg -i ./third-party/rabbitmq/libss<version>.deb
   dpkg -i ./third-party/rabbitmq/socat_<version>.deb
   dpkg -i ./third-party/rabbitmq/esl-erlang_<version>.deb

   ubuntu 18.04 (bionic)

   dpkg -i ./third-party/rabbitmq/socat_<version>.deb
   dpkg -i ./third-party/rabbitmq/esl-erlang_<version>.deb

   ubuntu 20.04 (focal)

   dpkg -i ./third-party/rabbitmq/socat_<version>.deb
   dpkg -i ./third-party/rabbitmq/esl-erlang_<version>.deb

   Debian 8 (jessie)

   # Before installing Erlang dependencies
   mv /etc/apt/sources.list.d/backports.list /etc/apt >/dev/null
   
   apt-get update
   dpkg -i ./third-party/rabbitmq/libss<version>.deb
   dpkg -i ./third-party/rabbitmq/socat_<version>.deb
   dpkg -i ./third-party/rabbitmq/esl-erlang_<version>.deb
   
   # After installing Erlang dependencies
   mv /etc/apt/backports.list /etc/apt/sources.list.d/backports.list >/dev/null
   apt-get update

   Debian 9 (stretch)

   dpkg -i ./third-party/rabbitmq/socat_<version>.deb
   dpkg -i ./third-party/rabbitmq/esl-erlang_<version>.deb

   Debian 10 (buster)

   dpkg -i ./third-party/rabbitmq/socat_<version>.deb
   dpkg -i ./third-party/rabbitmq/esl-erlang_<version>.deb

   Run the following commands if you have any issues running the above commands to install the dependencies. These will include any missing dependencies from your system.

   Install any missing dependancies

   apt-get update
   apt-get install -f -y
   apt-get update

5. Install Xray. You must run as a root user.

   dpkg -i ./xray/xray.deb

6. 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 configuration file

      Verify that a large file handle limit is specified before you start Xray. 

7. Start and manage the Xray service.
   

   systemd OS

   systemctl start|stop xray.service

   systemv OS

   service xray start|stop|status|restart

8. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

9. Check Xray Log.
   

   Linux

   tail -f $JFROG_HOME/xray/var/log/console.log

Helm Installation

1. Add the ChartCenter Helm repository to your Helm client.
   

   helm repo add jfrog https://charts.jfrog.io 
   

2. Update the repository.
   

   helm repo update

3. Initiate installation by providing a join key and JFrog url as a parameter to the Xray chart installation.

   helm upgrade --install xray --set xray.joinKey=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY> \
                --set xray.jfrogUrl=<YOUR_PREVIOUSLY_RETRIEVED_BASE_URL> --namespace xray jfrog/xray

   Alternatively, you can manually create a secret containing the join key and then pass it to the template during install/upgrade. The key must be named join-key.

   kubectl create secret generic my-secret --from-literal=join-key=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>
   
   # Pass the created secret to helm
   helm upgrade --install xray --set xray.joinKeySecretName=my-secret --namespace xray jfrog/xray

   In either case, make sure to pass the same join key on all future calls to helm install and helm upgrade. This means always passing --set xray.joinKey=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>. In the second, this means always passing --set xray.joinKeySecretName=my-secret and ensuring that the contents of the secret remain unchanged.

4. Customize the product configuration (optional) including database, Java Opts, and filestore.
   

   Unlike other installations, Helm Chart configurations are made to the values.yaml and are then applied to the system.yaml.

   Follow these steps to apply the configuration changes.

   1. Make the changes to values.yaml. 

   2. Run the command.
      

      helm upgrade --install xray --namespace xray -f values.yaml

5. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

6. Check the status of your deployed Helm release.
   

   helm status xray

HA Installation

The following describes how to set up an Xray HA cluster with two or more nodes. For more information, see the System Architecture.

Prerequisites

All nodes within the same Xray HA installation must be running the same Xray version.

Database

Xray HA requires an external PostgreSQL database. Make sure to install the database before proceeding to install the first node. There are several ways to set up PostgreSQL for redundancy, such as Load Balancing and Replication. For more information, see PostgreSQL.

RabbitMQ is automatically installed as part of the Xray installation for every node. In an HA architecture, RabbitMQ uses queue mirroring between the different RabbitMQ nodes, which are set up automatically.

Licensing

Xray HA is supported with an Enterprise License. Each node in the cluster must be activated with a different license.

Network

• All the Xray HA components (Xray cluster nodes, database server and RabbitMQ) must be within the same fast LAN.

• All the HA nodes must communicate with each other through dedicated TCP ports.

The following installation methods are supported:

• Linux Archive / RPM / Debian
• Docker Compose
• Helm

Linux Archive / RPM/ Debian Installation

First node installation steps:

1. Install the first node. The installation is identical to the single node installation. Important: make sure not to start Xray.

2. Configure the system.yaml file with the database and first node configuration details. For example,
   

   First node system.yaml

   shared:
     database:
       type: postgresql
       driver: org.postgresql.Driver
       url: postgres://<ip:port>/xraydb?sslmode=disable
       username: xray
       password: xray
     jfrogUrl: <JFrog URL>
     security:
       joinKey: <Artifactory Join Key>

3. Start and manage the Xray service.
   

   systemd OS

   systemctl start|stop xray.service

   Systemv OS

   service xray start|stop

4. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

5. Check the Xray log.
   

   Linux

   tail -f $JFROG_HOME/xray/var/log/console.log

Additional node installation steps:

For a node to join a cluster, the node must have the same database configuration and the Master Key.

1. Install all additional nodes using the same steps described above.
2. Configure PostgreSQL to allow external IP connections. This will ensure PostgreSQL is reachable by this node.

3. Configure the system.yaml file for the additional node with master key, database and active node configurations. For example,

   Additional node system.yaml

   shared:
     database:
       type: postgresql
       driver: org.postgresql.Driver
       url: postgres://<ip:port>/xraydb?sslmode=disable
       username: xray
       password: xray
     jfrogUrl: <JFrog URL>
     security:
       joinKey: <Artifactory Join Key>
     rabbitMq:
       active:
         node:
           name: 
           ip: 

4. Copy the master.key from the first node to the additional node located at $JFROG_HOME/xray/var/etc/security/master.key.

5. Start the additional node.

6. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

7. Check the Xray log.
   

   Linux

   tail -f $JFROG_HOME/xray/var/log/console.log

Docker Compose Installation

First node installation steps:

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

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

   .env file included within the Docker-Compose archive

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

   Notice that 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. Run the config.sh script to setup folders with required ownership. Note: the script will prompt you with a series of mandatory inputs, including if this is part of a cluster, and configure the needed system.yaml.
   

   ./config.sh

3. Validate and customize the product configuration (optional), including the third party dependencies connection details and ports.

4. Start and manage Xray using docker-compose commands. Note: Run this command only from the extracted folder.
   

   cd jfrog-xray-<version>-compose
   
   # Starting from Xray 3.8x RabbitMQ has been moved to a compose file of its own, this needs to be started before starting other services
   docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
   
   # Starting from Xray 3.8x, PostgreSQL needs to be started before starting the other services.
   docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d
   
   docker-compose -p xray up -d
   
   docker-compose -p xray logs
   docker-compose -p xray ps
   docker-compose -p xray down

5. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

6. Check the Xray log.
   

   docker-compose -p xray logs

Additional node installation steps:

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

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

2. Run the config.sh script to setup folders with required ownership. Note: the script will prompt you with a series of mandatory inputs, including if this is part of a cluster, and configure the needed system.yaml.
   

   ./config.sh
   

3. Validate and customize the product configuration (optional), including the third party dependencies connection details and ports.
   
   

   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. Start and manage Xray using docker-compose commands. Note: Run this command only from  the extracted folder.

5. cd jfrog-xray-<version>-compose
   
   # Starting from Xray 3.8x RabbitMQ has been moved to a compose file of its own, this needs to be started before starting other services
   docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
   docker-compose -p xray up -d
   
   docker-compose -p xray logs
   docker-compose -p xray ps
   docker-compose -p xray down

6. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

7. Check the Xray log.
   

   docker-compose -p xray logs

Helm Installation 

helm upgrade --install xray --namespace xray --set replicaCount=3  --set rabbitmq-ha.replicaCount=3 center/jfrog/xray

1. Add the ChartCenter Helm repository to your Helm client.
   

   helm repo add jfrog https://charts.jfrog.io 
   

2. Update the repository.
   

   helm repo update

3. Next, create a unique master key; JFrog Xray requires a unique master key to be used by all micro-services in the same cluster. By default the chart has one set in values.yaml (xray.masterKey).
   

   For production grade installations it is strongly recommended to use a custom master key. If you initially use the default master key it will be very hard to change the master key at a later stage This key is for demo purpose and should not be used in a production environment.

   Generate a unique key and pass it to the template during installation/upgrade.
   

   # Create a key
   export MASTER_KEY=$(openssl rand -hex 32)
   echo ${MASTER_KEY}
   
   # Pass the created master key to Helm
   helm upgrade --install --set xray.masterKey=${MASTER_KEY} --namespace xray jfrog/xray

   Alternatively, you can create a secret containing the master key manually and pass it to the template during installation/upgrade.
   

   # Create a key
   export MASTER_KEY=$(openssl rand -hex 32)
   echo ${MASTER_KEY}
   
   # Create a secret containing the key. The key in the secret must be named master-key
   kubectl create secret generic my-secret --from-literal=master-key=${MASTER_KEY}
   
   # Pass the created secret to Helm
   helm upgrade --install xray --set xray.masterKeySecretName=my-secret --namespace xray jfrog/xray

   In either case, make sure to pass the same master key on all future calls to helm install and helm upgrade. In the first case, this means always passing --set xray.masterKey=${MASTER_KEY}. In the second, this means always passing --set xray.masterKeySecretName=my-secret and ensuring the contents of the secret remain unchanged.

4. Initiate installation by providing a join key and JFrog url as a parameter to the Xray chart installation.

   helm upgrade --install xray --set xray.joinKey=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY> \
                --set xray.jfrogUrl=<YOUR_PREVIOUSLY_RETRIEVED_BASE_URL> --namespace xray jfrog/xray

   Alternatively, you can manually create a secret containing the join key and then pass it to the template during install/upgrade. The key must be named join-key.
   

   kubectl create secret generic my-secret --from-literal=join-key=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>
   
   # Pass the created secret to helm
   helm upgrade --install xray --set xray.joinKeySecretName=my-secret --namespace xray jfrog/xray

   In either case, make sure to pass the same join key on all future calls to helm install and helm upgrade. This means always passing --set xray.joinKey=<YOUR_PREVIOUSLY_RETRIEVED_JOIN_KEY>. In the second, this means always passing --set xray.joinKeySecretName=my-secret and ensuring that the contents of the secret remain unchanged.

5. Customize the product configuration (optional) including database, Java Opts, and filestore.

   Unlike other installations, Helm Chart configurations are made to the values.yaml and are then applied to the system.yaml.

   Follow these steps to apply the configuration changes.

   1. Make the changes to values.yaml. 

   2. Run the command.
      

      helm upgrade --install xray --namespace xray -f values.yaml

6. Access Xray from your browser at: http://<jfrogUrl>/ui/: go to the Xray Security & Compliance tab in the Administration module in the UI

7. Check the status of your deployed helm releases.
   

   helm status xray

Product Configuration

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

Artifactory Connection Details

Xray requires a working Artifactory server and a suitable license. The Xray connection to Artifactory requires 2 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.yaml file.
• 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.

Changing PostgreSQL Database Credentials

Xray comes bundled with a postgreSQL Database out-of-the-box, which come pre-configured with 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.

Changing RabbitMQ Database Credentials

Docker Compose

To change the default credentials.

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

   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

RPM/Debian

To change the default credentials.

1. Set the new password in the$JFROG_HOME/app/bin/rabbitmq/rabbitmq.conffile.
   

   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.
   

   service xray restart / systemctl restart xray.service

Linux Archive

To change the default credentials.

1. Set the new password in the$JFROG_HOME/app/bin/rabbitmq/rabbitmq.conffile.
   

   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.

   xray/app/bin/xray.sh restart 

Configuring 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
       #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
   #  shared:
   #    rabbitMq:
   #      active:
   #        node:
   #          name: <long hostname of active node>

   Linux and Native Installers

   In JFROG_HOME/app/bin/xray.default:
   
      export RABBITMQ_USE_LONGNAME=true

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 will cause the generated log files to inherit the folder's group permissions.

Third Party Applications

max_connections = 300

Installing PostgreSQL

RPM

1. Install PostgreSQL.
   

   Prior to Xray v 3.24.x

   # Run the following commands from the extracted jfrog-xray-<version>-rpm directory.
   # Note : Use PostgreSQL rpms with el7 when installing on Centos 7 and RHEL 7, and el8 with CentOS 8 and RHEL8.
   
   mkdir -p /var/opt/postgres/data
   
   rpm -ivh --replacepkgs ./third-party/postgresql/libicu-50.2-4.el7_7.x86_64.rpm (only AWS instance)
   rpm -ivh --replacepkgs ./third-party/postgresql/postgresql13-libs-13.2-1PGDG.rhel7.x86_64.rpm
   rpm -ivh --replacepkgs ./third-party/postgresql/postgresql13-13.2-1PGDG.rhel7.x86_64.rpm
   rpm -ivh --replacepkgs ./third-party/postgresql/postgresql13-server-13.2-1PGDG.rhel7.x86_64.rpm
   
   chown -R postgres:postgres /var/opt/postgres
   
   export PGDATA="/var/opt/postgres/data"
   export PGSETUP_INITDB_OPTIONS="-D /var/opt/postgres/data"
   
   # For centos 7&8 / rhel 7&8 
   sed -i "s~^Environment=PGDATA=.*~Environment=PGDATA=/var/opt/postgres/data~" /lib/systemd/system/postgresql-12.service
   systemctl daemon-reload
   /usr/pgsql-12/bin/postgresql-13-setup initdb
   
   # For centos 6 / rhel 6
   sed -i "s~^PGDATA=.*~PGDATA=/var/opt/postgres/data~" /etc/init.d/postgresql-13
   service postgresql-13 initdb
   
   Replace "ident" and "peer" with "trust" in postgres hba configuration file, /var/opt/postgres/data/pg_hba.conf. This configuration is for creating the initial users and database, once this is done, change "trust" to md5 in pg_hba.conf and restart PostgreSQL.
   

2. Configure PostgreSQL to allow external IP connections. 

3. By default PostgreSQL will only allow localhost clients communications. To enable different IPs to communicate with the database you will need to configure the pg_hba.conf file.
   

   File location according to installation type

   • Docker-compose: $JFROG_HOME/xray/var/data/postgres/data
   • Native installations: /var/opt/postgres/data

   To grant all IPs access you may add the below, under the IPv4 local connections section.
   

   host    all             all             0.0.0.0/0               md5

    Add the following line to /var/opt/postgres/data/postgresql.conf.
   

   listen_addresses='*'
   port=5432

   
   

4. Start PostgreSQL.
   

   systemctl start postgresql-<version>.service 
   
   or 
   
   service postgresql-<version> start

   
   

5. Setup the database and user.
   

   ## run the script to seed the tables and schemas needed by Xray
   cp -f ./third-party/postgresql/createPostgresUsers.sh /tmp
   source /etc/locale.conf
   
   cd /tmp && su postgres -c "POSTGRES_PATH=/usr/pgsql-12/bin PGPASSWORD=postgres DB_PASSWORD=password bash /tmp/createPostgresUsers.sh"

Debian   

Prerequisites

It is recommended to ensure your apt-get libraries are up-to-date, using the following commands.

apt-get update
apt-get install -f -y
apt-get update

# Create the file repository configuration to pull postgresql dependencies

cp -f /etc/apt/sources.list /etc/apt/sources.list.origfile
sh -c 'echo "deb http://ftp.de.debian.org/debian/ $(lsb_release -cs) main non-free contrib" >> /etc/apt/sources.list'
sh -c 'echo "deb-src http://ftp.de.debian.org/debian/ $(lsb_release -cs) main non-free contrib" >> /etc/apt/sources.list'  
  
cp -f /etc/apt/sources.list.d/pgdg.list /etc/apt/sources.list.d/pgdg.list.origfile
sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ $(lsb_release -cs)-pgdg main" >> /etc/apt/sources.list.d/pgdg.list'
sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" >> /etc/apt/sources.list.d/pgdg.list'

wget --no-check-certificate --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

Install Steps

1. Install PostgreSQL.
   Run the following commands from the extracted jfrog-xray-<version>-deb directory.

   mkdir -p /var/opt/postgres/data
   
   

   Ubuntu 16.04 (xenial)

   dpkg -i ./third-party/postgresql/postgresql-13_13.2-1.pgdg16.04+1_amd64.deb

   Ubuntu 18.04 (bionic)

   dpkg -i ./third-party/postgresql/postgresql-13_13.2-1.pgdg18.04+1_amd64.deb

   Ubuntu 20.04 (focal)

   dpkg -i ./third-party/postgresql/postgresql-13_13.2-1.pgdg20.04+1_amd64.deb

   Debian 8 (jessie)

   ## Before installing Postgres dependencies
   mv /etc/apt/sources.list.d/backports.list /etc/apt >/dev/null
   apt-get update
   dpkg -i ./third-party/postgresql/postgresql-13_13.2-1.pgdg80+1_amd64.deb
   
   # After installing Postgres dependencies
   mv /etc/apt/backports.list /etc/apt/sources.list.d/backports.list >/dev/null
   apt-get update

   Debian 9 (stretch)

   dpkg -i ./third-party/postgresql/postgresql-13_13.2-1.pgdg90+1_amd64.deb

   Debian 10 (buster)

   apt update -y 
   apt-get install wget sudo -y 
   apt-get install -y gnupg gnupg1 gnupg2 
   dpkg -i ./third-party/postgresql/postgresql-13_13.2-1.pgdg100+1_amd64.deb

2. Stop the Xray service.
   

   systemctl stop postgresql.service

3. Change permissions for the postgres folder.

   chown -R postgres:postgres /var/opt/postgres
   
   sed -i "s~^data_directory =.*~data_directory = '/var/opt/postgres/data'~" "/etc/postgresql/13/main/postgresql.conf"
   sed -i "s~^hba_file =.*~hba_file = '/var/opt/postgres/data/pg_hba.conf'~" "/etc/postgresql/13/main/postgresql.conf"
   sed -i "s~^ident_file =.*~ident_file = '/var/opt/postgres/data/pg_ident.conf'~" "/etc/postgresql/13/main/postgresql.conf"
   
   su postgres -c "/usr/lib/postgresql/12/bin/initdb --pgdata=/var/opt/postgres/data"

4. Configure PostgreSQL to allow external IP connections. 

5. By default PostgreSQL will only allow localhost clients communications. To enable different IPs to communicate with the database you will need to configure the pg_hba.conf file.
   

   File Location According to Installation Type

   • Docker-compose: $JFROG_HOME/xray/var/data/postgres/data
   • Native installations: /var/opt/postgres/data

   To grant all IPs access you may add the below, under the IPv4 local connections section:
   

   host    all             all             0.0.0.0/0               trust

   Add the following line to /etc/postgresql/12/main/postgresql.conf

   listen_addresses='*'

6.  Start PostgreSQL 
   

   systemctl start postgresql.service 
   
   or 
   
   service postgresql start

7. Set up the database and user.
   

   ## run the script to seed the tables and schemas needed by Xray
   cp -f ./third-party/postgresql/createPostgresUsers.sh /tmp
   source /etc/default/locale
   
   cd /tmp && su postgres -c "POSTGRES_PATH=/usr/lib/postgresql/12/bin PGPASSWORD=postgres DB_PASSWORD=password bash /tmp/createPostgresUsers.sh"

8. Put back the original pgdg.list.
   

   mv /etc/apt/sources.list.d/pgdg.list /etc/apt/sources.list.d/pgdg.list.tmp &&
   cp -f /etc/apt/sources.list.d/pgdg.list.origfile /etc/apt/sources.list.d/pgdg.list

9. Remove backup files.

   rm -f /etc/apt/sources.list.d/pgdg.list.tmp
   rm -f /etc/apt/sources.list.d/pgdg.list.origfile

10. Put back the original sources.list.

    mv /etc/apt/sources.list /etc/apt/sources.list.tmp &&
    cp -f /etc/apt/sources.list.origfile /etc/apt/sources.list

11. Remove the backup files.

    rm -f /etc/apt/sources.list.tmp &&
    rm -f /etc/apt/sources.list.origfile

 Linux Archive

 
# Create the psql database (the script "xray/app/third-party/postgresql/createPostgresUsers.sh" , responsible for seeding Postgres assumes this database exists)
<pgsql bin path>/psql template1
<postgres prompt>: CREATE DATABASE <user_name>;
<postgres prompt>: \q
 
## run the script to seed the tables and schemas needed by Xray
POSTGRES_PATH=<pgsql bin path> xray/app/third-party/postgresql/createPostgresUsers.sh

Installing Erlang

RPM

# Note : Use rpms with el7 when installing on Centos 7 and RHEL 7, and el8 with CentOS 8 and RHEL8.
rpm -ivh --replacepkgs xray/app/third-party/rabbitmq/socat-<version>.rpm
rpm -ivh --replacepkgs xray/app/third-party/rabbitmq/erlang-<version>.rpm

Debian

apt-get update
apt-get install -f -y
apt-get update

dpkg -i xray/app/third-party/rabbitmq/libss<version>.deb
dpkg -i xray/app/third-party/rabbitmq/socat_<version>.deb
dpkg -i xray/app/third-party/rabbitmq/esl-erlang_<version>.deb

dpkg -i xray/app/third-party/rabbitmq/socat_<version>.deb
dpkg -i xray/app/third-party/rabbitmq/esl-erlang_<version>.deb

# Before installing Erlang dependencies
mv /etc/apt/sources.list.d/backports.list /etc/apt >/dev/null

apt-get update
dpkg -i xray/app/third-party/rabbitmq/libss<version>.deb
dpkg -i xray/app/third-party/rabbitmq/socat_<version>.deb
dpkg -i xray/app/third-party/rabbitmq/esl-erlang_<version>.deb

# After installing Erlang dependencies
mv /etc/apt/backports.list /etc/apt/sources.list.d/backports.list >/dev/null
apt-get update

dpkg -i xray/app/third-party/rabbitmq/socat_<version>.deb
dpkg -i xray/app/third-party/rabbitmq/esl-erlang_<version>.deb

Installing Db-Util

RPM

# This will install db-util if db_dump is not available
hash db_dump 2>/dev/null || rpm -ivh --replacepkgs xray/app/third-party/misc/db4-utils-<version>.rpm

DEB

dpkg -i xray/app/third-party/misc/db5.3-util_<version>.deb
dpkg -i xray/app/third-party/misc/db-util_<version>.deb

dpkg -i xray/app/third-party/misc/db5.3-util_<version>.deb
dpkg -i xray/app/third-party/misc/db-util_<version>.deb

dpkg -i xray/app/third-party/misc/db5.3-util_<version>.deb
dpkg -i xray/app/third-party/misc/db-util_<version>.deb

For Advanced Users

Manual Docker Compose Installation

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

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

   Notice that some operating systems do not display dot files by default. If you've made any changes to the file, remember to backup before an upgrade.

2. Create the following folder structure under $JFROG_HOME/xray.
   

   |-- [         ]  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. If not entered, the script will prompt you for this input. 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.1

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 configuration file.
      

      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.
   

   ## RabbitMQ needs to be started before starting other services
   docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
     
   ## From Xray 3.8.x, PostgreSQL needs to be started 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 ps

10. Access Artifactory from your browser at: http://SERVER_HOSTNAME/ui/. For example, on your local machine: http://localhost/ui/.

11. Check Xray log.
    

    docker ps
    docker-compose -p xray logs

    Configuring the Log Rotation of the Console Log

    The console.log file can grow quickly since all services write to it. The installation scripts add a cron job to log rotate the console.log file every hour.

    This is not  done for manual Docker Compose installations. Learn more on how to configure the log rotation.

Watch the Screencast