Chapter 2. Installing the web console

You can install the web console on Linux, Windows, macOS, or OpenShift Container Platform.

2.1. Installing the web console on Linux, Windows, or macOS

You can install the web console on Linux, Windows, or macOS operating systems and access the web console in a browser.

The web console has been tested with Chrome and Firefox.

Prerequisites

  • OpenJDK 1.8, OpenJDK 11, Oracle JDK 1.8, or Oracle JDK 11
  • 8 GB RAM
  • macOS: The value of maxproc must be 2048 or greater.

Procedure

  1. Download the installation archive file from the MTA Download page.

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

    Note

    If you are installing on a Windows operating system, extract the .zip file to a folder named mta to avoid a Path too long error.

    The directory is referred to as <MTA_HOME> in this guide.

  3. Start the web console:

    • Linux operating system: 

      $ <MTA_HOME>/run_mta.sh

    • Windows operating system: 

      C:\<MTA_HOME>\run_mta.bat

  4. Open a browser and navigate to http://localhost:8080/mta-web.

    Figure 2.1. Welcome Page

    Welcome Page

    The web console installation creates a default mta user with a default password, password. You can add additional users to the web console.

2.2. Installing the web console on OpenShift Container Platform

You can install the MTA web console on Red Hat OpenShift Container Platform and access the web console in a browser.

2.2.1. Understanding the web console image

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

The MTA image installs the following Pods:

  • The Executor Pod runs analyses and generates reports
  • The Web Console + Red Hat Single Sign-on (SSO) Pod provides access to the web console
  • The PostgreSQL Pod stores the project’s configuration and analysis tracking information

A separate persistent volume is used for the web console interface and the PostgreSQL Pods. The Executor Pod’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. 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.2. Importing a web console template

You can import a web console template into Red Hat OpenShift Container Platform.

Prerequisites

  • OpenShift Container Platform version 3.11 or 4.x.

    The web console installation has been tested on OpenShift Container Platform 3.11 and 4.4. Other versions of 4.x should be compatible.

Procedure

  1. Download the installation archive file from the MTA Download page.

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

    The directory is referred to as <MTA_HOME> in this guide.

  3. Launch the OpenShift web console.

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

  5. Fill in the following fields:

    • Project Name. Mandatory.
    • Project Display Name. Optional. This field determines how the project name is displayed in the web console.
    • Project Description. Optional.
  6. Click Browse and import the desired web console template from <MTA_HOME>/openshift/templates.
  7. Click Create.
  8. Optional: To save the template as a resource for future projects, select Save template.
  9. Click Continue.
  10. Review the values provided.

  11. Click Create to import the template into your project.

    The web console template is imported into your project.

2.2.3. Accessing the web console

Once the web console has been deployed on OpenShift Container Platform, 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 MTA Web Console ...
Upload, build and deployment successful!

Open <WEB_CONSOLE_URL> to start using the MTA Web Console on OpenShift (user='mta',password='<password>')

You can also access the web console from the OpenShift console at <OPENSHIFT_URL>/console/project/mta/overview by clicking the link in the MTA WEB CONSOLE HTTP application. If you renamed the OpenShift project when deploying, replace mta 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

The web console installation creates a default mta user with a default password, password. You can add additional users to the web console.

2.2.4. Troubleshooting

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.

2.2.4.1. Obtaining the latest image

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, no image stream is created and the following steps are not applicable.

Procedure

  1. Open the OpenShift console.
  2. Click Builds → Images.
  3. Ensure that the column under Tags indicates that each image is on the latest stream.
  4. If the latest image is not in use, follow the steps for the OpenShift installation to redeploy the latest image of the web console.

2.2.4.2. Examining and collecting 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.

OpenShift console

You can download a Pod’s log with the OpenShift Container Platform console.

Procedure

  1. Open the OpenShift console and navigate to Applications → Pods.
  2. Click the name of the Pod that you wish to examine. To examine the current web console Pod, select the mta-web-console-<POD_NAME> that is in a Running state.
  3. Click Logs.
  4. Click Download to download and save a log.

CLI

You can download a Pod’s log with the CLI.

Procedure

  1. Obtain the Pod names: 

    $ oc get pods

    The output resembles the following: 

    NAME                       READY     STATUS      RESTARTS   AGE
eap-builder-1-build        0/1       Completed   0          1d
mta-postgresql-1-hfbdn     1/1       Running     0          1d
mta-sso-1-build            0/1       Completed   0          1d
mta-web-console-1-build    0/1       Completed   0          1d
mta-web-console-1-vt7s5    1/1       Running     1          1d
sso-1-wjl2n                1/1       Running     1          1d

  2. Use oc logs to examine the 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> > ./mta-openshift-<POD_NAME>.log

2.2.4.3. Common issues

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.

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.

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 mta-web-console-executor-1: Pods for rc 'mta/<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.4.4. Reporting issues

The Migration Toolkit for Applications 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 Migration Toolkit for Applications (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. 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 MTA development team, attach it to the issue using the browse button.

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