Installing iCR for Java

It is quick and easy to get going on analyzing and automatically correcting programming errors in your Java projects. With your iCR for Java subscription (either paid or a Proof of Concept subscription), you will have been sent a message with 2 important items:

1. A link to a zip file containing the items listed below; and

2. A file named license.json which contains your unique software license.

These items will be explained in this section.

The examples in the guide will be using Linux as the reference platform. Support for platforms other than Linux will be supported in future releases. All of the installation and configuration shown in this section will be performed from a command line interface. So, your first step would be to SSH into your server and login.

Your Linux system must also be configured with two important packages:

1. You must have the zip/unzip package. This is frequently already installed on your Linux distribution but, if not, you will need to install it since the iCR for Java package is distributed in zip format;

2. The iCR for Java framework is designed to operate within a Docker environment. Docker allows you to install packages like iCR on 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 icrforjava commands will not require typing sudo before each command invocation.

Once your system is configured with the required packages you can install the iCR for Java package.

To begin, from the command line, choose a directory to use for staging the installation. It can be any user directory. Once selected, copy the license.json file that was attached to your email to that directory.

Your license will enable iCR for Java to execute on sny platform upon which it has been installed. The license manages usage through tracking consumption. If more than one platform is running iCR, they can share the license and the total consumption will be reduced as the analyses complete.

Your license is enabled for a period of time and for a maximum number of OpenRefactory Bundled Lines of Code (OBLoCs). OBLoCs consist of only those executable lines of code that are actually used in the analysis. This means that whitespace and most comments are NOT counted against your licensed capacity. To get an estimate of a project’s OBLoC count, you can use the Linux utility cloc.

Should you exhaust your OBLoC capacity, iCR for Java will not be able to continue. In this case contact OpenRefactory to learn how to extend your license.

iCR for Java is implemented using Docker containers. The container image that you will be using is located on the Docker Hub server. If you are unfamiliar with Docker Hub, you can learn more about it here. If you are using a private Docker Hub then you may clone the container into your own Docker Hub. To determine the container to be cloned, please use the link that was included in your package message.

Use the link, which is included in your package email, to download the zip file into the same directory where you placed your license file. Use the unzip command to expand the contents into that directory. For the examples used here, we will use: /home/userid/tools/icr as the example folder/directory.

The expanded files are:

1. install-icr:

   This is the script used to install iCR for Java on your host system;

2. icrforjava:

   This is the command used to manage your server after installation. Use it to start up your iCR for Java service, update configuration values or even remove it from your host server completely;

3. EULA_for_iCR:

   This is the End-User license which gives you the authority to use the iCR for Java on your private platform. You must have read and accepted this prior to receiving and installing this package.

4. icr-CICD-package:

   This is a subdirectory which holds 6 other files which may be used to integrate iCR into Jenkins, GitHub Actions or GitLab CI/CD pipelines. To learn more about how to use iCR in a CI/CD pipeline framework, refer to the companion CI/CD Integration Guide. The subdirectory contains:

   • icrPlugin.hpi:

     iCR for Java supports Jenkins workflows which use a plugin to be inserted into workflows to trigger iCR. This file is the plugin which would be used with Jenkins.

   • icr-gitlab.tar:

     This is the file containing the code that can be executed by GitLab to start an analysis via a CI/CD pipeline in GitLab.

   • icr-github.tar: This is the file containing the Docker image to be executed by GitHub to start an analysis via a CI/CD pipeline in GitHub Actions.

   • prep-container.sh:

     For simplicity and convenience, OpenRefactory provides a simple script to make it easier to prepare the iCR code for insertion into the GitLab or GitHub CI/CD container registry.

   • icr-gitlab-ci.yml:

     When using a GitLab CI/CD pipeline, a yml script is saved in each desired repository to activate iCR when the pipeline is executed. This is the sample script to be inserted into the User’s repository to cause iCR to be correctly invoked.

   • githubAction.yml:

     When using a GitHub CI/CD pipeline, a yml script is required in each desired repository to activate iCR when the pipeline is executed. This is the sample script to be inserted into the User’s repository to cause iCR to be correctly invoked.

With the zip file expanded, install the iCR for Java components. To do that, execute the install-icr command. This installation step will require root privileges so MUST be done using sudo. Run the command as follows:

sudo ./install-icr <Private Docker Hub URL>

The optional argument <Private Docker Hub URL> must be provided if you are loading the container from your private Docker Hub repository. If the argument is absent, the install script will default to the cloud-based Docker Hub.

You should see output that looks like the following:

034acb3a48e7: Loading layer [======================================>] 253.1MB/253.1MB
dd925e02d664: Loading layer [======================================>] 1.313GB/1.313GB
0537bb84bd7d: Loading layer [======================================>] 720.6MB/720.6MB
Loaded image: icr-for-Java:local

This will accomplish a number of things for you:

• The Docker image will be installed into your Docker registry under the name icr-for-Java:local;

• The scripts will be copied to usr/bin where they will be accessible to all your developers who have access to your host system;

• The companion files, such as the EULA, will be saved in your /etc directory in a new directory named /etc/icr-data;

Once the above files are installed on your iCR host system, and if you are planning on integrating iCR into your Jenkins, GitLab or GitHub Apps CI/CD pipeline(s), you may want to copy the CI/CD support scripts from the icr-CICD-package subdirectory. The Jenkins plugin should be copied into the default directory (/var/lib/jenkins/plugins/) on the server where you plan to run your Jenkins workflows. The GitLab yml script goes into the various repositories where you want to use CI/CD. The GitHub yml script should be used as a template for those GitHub projects where you desire CI/CD integration.