Installing and setting up

After you configure IBM® ADDI for Z Refactoring Assistant, check the instructions to install and set up Z Refactoring Assistant.

Note: Installing Z Refactoring Assistant requires downloading the OrientDB docker image. Since an air-gapped system cannot directly download the necessary docker image, you need to manually download and transfer the image. To install Z Refactoring Assistant on an air-gapped system, complete the following extra steps before your installation:
  1. On a Linux system with internet access, run the following command:
    podman save orientdb:3.2.28 > orientdb.tar
    Starting with May 2024 release, OrientDB version 3.2.28 or later is required for Z Refactoring Assistant.
  2. Transfer the orientdb.tar to the air-gapped system where you want to install Z Refactoring Assistant.
  3. Run the following command:
    podman load -i orientdb.tar
  4. Proceed with the normal installation process for Z Refactoring Assistant.
To install and set up Z Refactoring Assistant, complete the following steps:
  1. Open a terminal window.
  2. Extract the Z Refactoring Assistant archive file by running the following command:
    tar -xzvpf refactoring-assistant-<version>.tgz
    where <version> specifies the version of the file. Replace refactoring-assistant-<version>.tgz with the name of the Z Refactoring Assistant archive file that you obtained.
  3. In your Z Refactoring Assistant root directory, run the following command to install the Z Refactoring Assistant container images.
    ./setup.sh
  4. Copy the config/template.properties file to config/config.properties. Open config/config.properties in an editor and enter the values inside as instructed.
    Note: If your system has Security-Enhanced Linux (SELinux) feature enabled, you need to add the following additional property to the config.properties file.
    RA_MOUNT_OPTIONS=:Z
    You can refer to the following example:
    # Absolute path to directory where certificates and keys are kept
    CERTS_LOCATION=/path/to/certificates
    
    # Protocol to use to communicate with AD services
    PROTOCOL=https
    
    # The IBM AD configuration (ZooKeeper) connection string, e.g. hostname.mydomain.com:2181 
    # If using IBM ADDI versions prior to 6.1.3 ifix1, use port 2281 for a secured connection
    AD_HOST_PORT=windowsvm.mydomain.com:2181
    
    # Port numbers of the AD mainframe projects and file services respectively
    # AD_PROJ_PORT=7650
    # AD_FILE_PORT=7700
    
    # The environment ID, which can be obtained from the IBM Application Discovery Configuration Service Admin dashboard
    # https://www.ibm.com/docs/en/addi/latest?topic=configuring-by-using-ad-configuration-service
    ENVIRONMENT_ID=00000000-0000-0000-0000-000000000000
    
    # The location of the DEX authentication server, defaults to https://$AD_HOST:7600 if unset
    # DEX_HOST_PORT=
    
    # Outbound mail settings to enable email notifications
    # MAIL_HOST=
    # MAIL_PORT=
    # MAIL_USERNAME=
    # MAIL_PASSWORD=
    
    # Extra Java mail properties, which can be specified by using MAIL_PROPERTIES_ prefix
    # followed by the property name with dot separators replaced by underscores
    # MAIL_PROPERTIES_MAIL_SMTP_AUTH=true

    The </path/to/certificates> directory should be outside of your Z Refactoring Assistant root directory and it will be created if it does not exist.

    Important: The </path/to/certificates> directory is where the artifacts that are used for secure communications (such and certificates and keys) are kept. Ensure that the directory is secured with the appropriate access permissions.
    For the ENVIRONMENT_ID value, open the IBM Application Discovery Configuration Services Admin dashboard, click the Configure tab to see the environments available and copy the ID that you want.
    The image shows the Application Discovery Configuration Service Admin dashboard.

    For the email server configuration, it is optional. Configuring the email server will enable Z Refactoring Assistant to send you email notifications. To set the values, your organization's SMTP server settings need to be used.