Red Hat Training

A Red Hat training course is available for Red Hat Application Migration Toolkit

Chapter 2. Installing the Web Console

The web console can be installed either using the ZIP distribution or on OpenShift.

2.1. ZIP Installation

When installed using the ZIP distribution, the RHAMT web console is deployed on Red Hat JBoss Enterprise Application Platform, uses Red Hat Single Sign-On for authentication, and is backed by an H2 database for storage.

2.1.1. Prerequisites

Verify that you meet the following prerequisites.

  • Java Platform, JRE version 8+
  • A minimum of 8 GB RAM; 16 GB recommended
Note

If you are running macOS, it is recommended to set the maximum number of user processes, maxproc, to at least 2048, and the maximum number of open files, maxfiles, to 100000.

2.1.2. Install the Web Console

  1. Download the web console from the RHAMT Download page.

  2. Extract the ZIP file to a directory of your choice.

    The path to the directory created by unzipping this file is referred to as RHAMT_HOME throughout this guide.

2.1.3. Start the Web Console

Run the script to start the web console. 

$ RHAMT_HOME/run_rhamt.sh
Note

In a Windows environment, use the run_rhamt.bat script.

You can now access the web console from a browser.

2.1.4. Access the Web Console

Once started, the web console is accessible from a browser by default on the local host at http://localhost:8080/rhamt-web.

Figure 2.1. Welcome Page

Welcome Page

The web console uses a default user to automatically authenticate. The default user’s credentials are rhamt and password. See Configuring Authentication for the Web Console to require individual users to authenticate in order to access the web console.

2.2. OpenShift Installation

When installed on OpenShift, the RHAMT web console is deployed on Red Hat JBoss Enterprise Application Platform, uses Red Hat Single Sign-On for authentication, and is backed by a PostgreSQL database for storage.

2.2.1. Prerequisites

Verify that you meet the following prerequisites.

  • You must have access to an instance of OpenShift Container Platform version 3.5 or higher.
  • Your OpenShift instance must have the middleware image streams installed.
  • You must have the OpenShift Container Platform CLI installed on your local machine.
  • You must be running Linux or macOS on your local machine. Windows is not currently supported.

See the OpenShift Container Platform documentation for assistance.

2.2.2. Understanding the Web Console OpenShift Image

Red Hat offers containerized images for RHAMT that are designed for use with OpenShift. Using these images developers can quickly and easily manage migration projects and analyze applications.

The OpenShift images include three separate pods:

  • The executor, responsible for running the analysis and generating the reports
  • The web console interface and SSO, which provide access to the web console itself
  • The PostgreSQL database, which stores the project’s configuraton and analysis tracking information

A separate persistent volume is used for the web console interface and the PostgreSQL pods; however, the executor’s storage is dependent on the template used.

  • The web-template-empty-dir-executor.json is the recommended template. It configures the executor pod to use temporary storage on a single machine, and has no defined persistent volume. The analysis data is sent between the executor and web console pods using a RESTful web service.

    Figure 2.2. web-template-empty-dir-executor.json

    web-template-empty-dir-executor.json

  • The web-template-empty-dir-executor-shared-storage.json is an alternative template available for use. This template configures the executor pod and the web console pod to use a shared persistent volume. All instances of these pods read and write to the same persistent volume, mounted as ReadWriteMany in OpenShift.

    Figure 2.3. web-template-empty-dir-executor-shared-storage.json

    web-template-empty-dir-executor-shared-storage.json
OpenShift Template Environment Variables

The OpenShift image environment variables are configured as a baseline for application analysis, and work well in a variety of environments. No additional configuration is required to perform an analysis.

The most common environment variables modified are the CPU and memory resources allocated to each image. These contain a pattern of NODE_NAME followed by REQUESTED_RESOURCE. For instance, EXECUTOR_REQUESTED_CPU indicates the number of CPU cores to request for the executor pod, while EXECUTOR_REQUESTED_MEMORY indicates the amount of memory to request for the executor pod.

All of the environment variables are found within each template, along with a description of each.

2.2.3. Deploy the RHAMT Application

  1. Download the web console from the RHAMT Download page.

  2. Extract the ZIP file to a directory of your choice.

    The path to the directory created by unzipping this file is referred to as RHAMT_HOME throughout this guide.

  3. Access the OpenShift web console. It should appear similar to the following image.

    openshift console
  4. Click the Import YAML / JSON button in the top-right corner of the web console.

  5. Provide the following information in the window that appears, as seen below.

    openshift import template
    1. Define a Project Name, such as rhamt.
    2. Optionally, define a Project Display Name to help describe the project.
    3. Optionally, define a Project Description to help provide context on how the project will be used.
    4. Click the Browse button and import the desired web console template. These are included in RHAMT_HOME/openshift/templates. Once imported, the JSON is visible in the bottom text area.
  6. Click the Create button to proceed to the next screen.
  7. If you would like to save the template as a resource for future projects, check the Save template box.
  8. Click the Continue button to proceed to the next screen.
  9. Review the default values provided, adjusting as necessary. For instance, the web-template-empty-dir-executor.json file defines 2 CPUs, 4GB of memory, and a 20GB persistent volume.
  10. Click the Create button to import the template into your project.

Once completed, you can access the web console from a browser.

2.2.4. Access the Web Console

Once the web console has been deployed on OpenShift, you can access it from a browser. The deploy.sh script outputs the link, shown in the example below as WEB_CONSOLE_URL, to use to open the web console.

Example: deploy.sh Output

...
-> Deploy RHAMT Web Console ...
Upload, build and deployment successful!

Open WEB_CONSOLE_URL to start using the RHAMT Web Console on OpenShift (user='rhamt',password='password')

You can also access the web console from the OpenShift console at OPENSHIFT_URL/console/project/rhamt/overview by clicking the link in the RHAMT WEB CONSOLE HTTP application. If you renamed the OpenShift project when deploying, be sure to replace rhamt in this URL with the name of your project.

Note

If the web console does not load immediately, check the status of the project in the OpenShift console to see if it is still processing or if there were errors.

Figure 2.4. Welcome Page

Welcome Page

Authentication is required in order to access the web console. The default user’s credentials are rhamt and password. See Configuring Authentication for the Web Console for more information on configuring authentication for the web console.

2.2.5. Troubleshoot the Web Console OpenShift Install

The following steps discuss common techniques for troubleshooting the web console in an OpenShift environment. These instructions are focused on issues specific to the web console, for OpenShift specific issues refer to the following troubleshooting sections.

2.2.5.1. Ensure Latest Image Version

The first step in troubleshooting in an OpenShift environment is to ensure that the latest image is in use.

Note

If you have deployed the web console by pasting in a JSON template, then no image stream is created and the following steps are not applicable.

From your OpenShift environment perform the following steps.

  1. Access the OpenShift console by navigating to OPENSHIFT_URL/console/project/rhamt/overview. If you renamed the OpenShift project when deploying, be sure to replace rhamt in this URL with the name of your project.
  2. Hover over Builds along the left side of the console.
  3. Click Images from the options that appear.
  4. Ensure that the column under Tags indicates that each image is on the latest stream.
  5. If the latest image is not in use, follow the steps at OpenShift Installation to redeploy the latest image of the web console.

2.2.5.2. Examine and Collect the Web Console Logs

Each pod is configured to provide detailed logging that assists with narrowing down the precise cause of an issue. The following steps discuss viewing and obtaining these logs.

2.2.5.2.1. Using the OpenShift Console

The following steps walk through the process to examine the logs for each pod.

  1. Access the OpenShift console by navigating to OPENSHIFT_URL/console/project/rhamt/overview. If you renamed the OpenShift project when deploying, be sure to replace rhamt in this URL with the name of your project.
  2. Hover over Applications along the left side of the console.
  3. Click Pods from the options that appear.
  4. Click the name of the pod that you wish to examine. To examine the current web console pod, select the rhamt-web-console-POD_NAME that is in a Running state.
  5. Click Logs from the options along the top.
  6. To download the log file navigate to the top of the page and click Download.
2.2.5.2.2. Using the OpenShift Client

  1. Determine the pod name by executing oc get pods and search for the web-console entry with a Running status. 

    $ oc get pod
sNAME                        READY     STATUS      RESTARTS   AGE
eap-builder-1-build         0/1       Completed   0          1d
rhamt-postgresql-1-hfbdn    1/1       Running     0          1d
rhamt-sso-1-build           0/1       Completed   0          1d
rhamt-web-console-1-build   0/1       Completed   0          1d
rhamt-web-console-1-vt7s5   1/1       Running     1          1d
sso-1-wjl2n                 1/1       Running     1          1d

    In the above example this is rhamt-web-console-1-vt7s5.

  2. Use oc logs to examine the current pod’s log. 

    oc logs POD_NAME

  3. The output may be redirected to obtain a copy of the current log. 

    oc logs POD_NAME > ./rhamt-openshift-POD_NAME.log

2.2.5.3. Common Issues with Web Console OpenShift

2.2.5.3.1. Executor Pod Throws NoRouteToHostException

When accessing the executor pod’s logs the following error is seen. 

13:44:03,501 SEVERE [org.jboss.windup.web.messaging.executor.ExecutorBootstrap] (main) Could not start messaging listener due to: Failed to connect to any server. Servers tried: [http-remoting://192.0.2.4:8080 (java.net.NoRouteToHostException: No route to host)]: javax.naming.CommunicationException: Failed to connect to any server. Servers tried: [http-remoting://192.0.2.4:8080 (java.net.NoRouteToHostException: No route to host)]
[...]

What it means:

A NoRouteToHostException indicates that this pod isn’t able to connect to the web console pod.

How to resolve it:

In a new deployment this is expected, as the executor starts before the web console. Otherwise, examine the web console pod and resolve any errors seen here. Once the web console is running successfully this error should be resolved.

2.2.5.3.2. Pod Reports Insufficient Resources

After attempting to deploy Web Console on OpenShift, the pod is unable to start, and the following error is seen in the Events tab. 

0/9 nodes are available: 4 Insufficient cpu, 4 MatchNodeSelector, 9 Insufficient memory.

What it means:

The resource quota for the OpenShift project has been met, and the pod is unable to obtain the requested resources.

How to resolve it:

Perform either of the following:

  • Increase the quota for the OpenShift project. For additional information on OpenShift quotas, see Quotas and Limit Ranges and Setting Limit Ranges.
  • Reduce the requested resources for the web console OpenShift project. It is recommended to have at least 2 CPUs and 4 GB of memory for the project.

Once the request is within the available quota, attempt the deployment once again.

2.2.5.3.3. Pod Takes Longer than 600 seconds to become available

After attempting a deployment, the -deploy pods timeout and report the following error. 

error: update acceptor rejected rhamt-web-console-executor-1: pods for rc 'rhamt/POD_NAME' took longer than 600 seconds to become available

These errors appear after the pods timeout and are placed into an error state.

What it means:

The deployment pods are unable to successfully launch the pods.

This error can be caused by a number of sources, with the following being the most common:

  • The OpenShift instance is currently out of resources to deploy the pod in a timely manner.
  • The images were unable to be successfully pulled from the registry.

How to resolve it:

Attempt the deployment again, and view the logs and events of the non deployment pods while they are being created. These messages will provide context to the underlying errors resulting in the deployment pod timeouts.

  • To address the first issue reported, where the OpenShift instance is out of resources, follow the instructions in Analyzing Cluster Capacity from the Cluster Administration guide in the OpenShift documentation to determine the cluster capacity. Once the capacity has increased, or there are fewer jobs executing, attempt the deployment once again.
  • To address the second issue reported, where the images are unable to be pulled from the registry, access the registry to ensure the images are present. This link also includes instructions on examining the logs for the Docker registry, and can be used to troubleshoot the issue further.

2.2.5.4. Report Issues with Web Console OpenShift

{ ProductName} uses JIRA as its issue tracking system. If you encounter any issues while using the web console, please file a JIRA Issue by following the below instructions.

Note

If you do not have one already, you must sign up for a JIRA account in order to create a JIRA issue.

  1. Open a browser and navigate to the JIRA Create Issue page.

    If you have not yet logged in, click the Log In link at the top right side of the page and enter your credentials.

  2. Choose the following options and click the Next button.

    • Project: Choose Red Hat Application Migration Toolkit (WINDUP).
    • Issue Type: Bug

  3. On the next screen complete the following fields.

    • Summary: Enter a brief description of the problem or issue.
    • Environment: Indicate that this is an OpenShift installation of the web console, and include any environment variables in use with the image.
    • Description: Provide a detailed description of the issue. Be sure to include any errors encountered and exception traces.

    • Attachment: Include the logs obtained in Examine and Collect the Web Console Logs. At a minimum this should include the logs from each pod.

      If the application or archive causing the issue does not contain sensitive information and you are comfortable sharing it with the RHAMT development team, attach it to the issue using the browse button.

  4. Click the Create button to create the JIRA issue.