Installation of iCR CLI

The iCR CLI is a tool used to invoke the requested Anaysis Engine (AE) for the specified language. There is one AE for each supported language. Analysis is invoked using a simple command with arguments to specify the language desired where, to find the source code, and where to place the results.

To enable the iCR CLI, it must be installed on the platform being used to run the analyses. The platform must meet the system requirements for CPU, RAM and storage. Otherwise, analyses may be unable to execute properly.

The iCR analysis engines are designed to operate within a Docker environment. Docker allows you to install packages like iCR CLI onto your private Linux platform and know that it will be protected from other software on your system and your network. If you need to install Docker, please refer to the Docker installation instructions which can be found here: https://docs.docker.com/engine/install/.

NOTE: Once Docker is installed, you will want to follow the common practice of creating a User Group to allow Docker access without requiring root privileges for each user. To learn how to do that, please refer to this Docker post-install information. These instructions assume that you have done that so executing the docker commands will not require typing sudo before each command invocation.

To begin the installation process, from the command line, choose a directory to use for staging the installation. It can be any user directory. Place the extract_icr_pkg script provided to you by OpenrRefactory, in that directory along with your your license file (license.json). Make sure the extract_icr_pkg script is executable by using:

sudo chmod +x ./extract_icr_pkg

Then execute the command: ./extract_icr_pkg iCR-CLI:4.2.0

The argument iCR-CLI:4.2.0 is the name of the iCR CLI package to be used for this version of the CLI.

NOTE: Some installations may not permit direct access to DockerHub and use a private DockerHub repository. This allows organizations to scan the containers prior to installing them. If this is the case for your installation, the extract_icr_pkg command takes an optional argument, ./extract_icr_pkg [<registry-URL>] iCR-CLI:4.2.0, where <registry_URL> is the URL to your private DockerHub. Contact OpenRefactory for more information if this is something that you require.

This will fetch the named package from DockerHub or your private registry and will install it into Docker on your system. Once extracted, you will see the following in your installation directory:

1. EULA_for_iCR

   This is the End-User License Agreement which gives you the authority to use the iCR analysis engines on your private platform. You must have read and accepted this prior to receiving and installing this package;

2. install-icr-cli

   This script is used to preload all of the language specific Analysis Engine containers into your local Docker registry. These will be invoked using the icr-cli command;

3. icr-cli

   This is the CLI command used to invoke the analysis engine for a specific language and version where applicable;

4. SBOMs/

   This directory contains the Software Bill of Materials or SBoM files which identify all of the packages included in the iCR CLI software. This is used to let you know what components are being included within the iCR Docker containers. There is one SBOM json file for each container used in iCR.

5. sample-github-ci-yaml

   This file provides a sample version of a GitHub Actions yaml file that uses the iCR CLI as part of a workflow. It is offered here as an example of how the CLI might be used in a CI/CD workflow.

With the files extracted, install the iCR Analysis Engine containers using the install-icr-cli command. This installation step will require root privileges so MUST be done using sudo. Run the command as follows:

sudo ./install-icr-cli

As the installation proceeds you will see a lot of messages from Docker tracking the installation from DockerHub or your local registry. It should appear similar to the sequence shown below:

~/products/icr_cli4.2$ sudo ./install-icr-cli 
Installation is in progress...
Try to pull all engines ...
4.2.0: Pulling from openrefactory/icr-java-engine
Digest: sha256:3230b16f5f33eb26cdb64f970b076a8adbbb1e71fa82dba8e8fee095d0837c57
Status: Image is up to date for openrefactory/icr-java-engine:4.2.0
docker.io/openrefactory/icr-java-engine:4.2.0
4.2.0: Pulling from openrefactory/icr-python-engine
Digest: sha256:ea920fb3417dcbbdc3ded211507ecd93bd7701b7d4330b314aa05da0bd54f01e
Status: Image is up to date for openrefactory/icr-python-engine:4.2.0
docker.io/openrefactory/icr-python-engine:4.2.0
4.2.0: Pulling from openrefactory/icr-go-engine
Digest: sha256:960083e0e138f075d8fb0660143920e91de1119af1bf9f8c13b8942d803023eb
Status: Image is up to date for openrefactory/icr-go-engine:4.2.0
docker.io/openrefactory/icr-go-engine:4.2.0

Once the Docker containers are installed, the installation script also sets up the icr-cli command for you so that you can immediately use it.

As a check, you can use the docker images command to see the new iCR containers:

~/products/icr_cli4.2$ docker images
REPOSITORY                         TAG       IMAGE ID       CREATED          SIZE
openrefactory/icr-cli              4.2.0     dc15f0fe6466   38 minutes ago   107MB
openrefactory/icr-java-engine      4.2.0     86c847bda13e   2 days ago       1.82GB
openrefactory/icr-python-engine    4.2.0     e1815e835e65   2 days ago       2.89GB
openrefactory/icr-go-engine        4.2.0     9487d7b659b7   2 days ago       573MB

You iCR CLI is now ready for use.