Chapter 2. Installing the web console

You can install the web console on Linux, Windows, macOS, or Red Hat 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

  • Java Development Kit (JDK) installed. MTR supports the following JDKs:

    • OpenJDK 11
    • Oracle JDK 11
  • 8 GB RAM
  • macOS installation: the value of maxproc must be 2048 or greater.

Procedure

  1. Navigate to the MTR Download page and download the web console Local install & OpenShift file.

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

    Note

    If you are installing on a Windows operating system:

    1. Extract the .zip file to a folder named LC_PSN to avoid a Path too long error. Alternatively, extract the file with 7-Zip to a folder of any name you choose.
    2. If a Confirm file replace window is displayed during extraction, click Yes to all.

    When you encounter <MTR_HOME> in this guide, replace it with the actual path to your MTR installation.

  3. By default, no authentication is required. If you wish to enable authentication, do this before starting the web console.

  4. Start the web console:

    • Linux or macOS operating system: 

      $ <MTR_HOME>/run_windup.sh

    • Windows operating system: 

      C:\<MTR_HOME>\run_windup.bat

  5. Open a browser and navigate to http://localhost:8080/windup-ui.

    If authentication is not configured, the Projects screen is displayed in your browser.

    Figure 2.1. MTR Projects screen

    web console projects screen

2.2. Installing the web console on OpenShift Container Platform 4.6 and later

You can install the web console on OpenShift Container Platform 4.6 and later versions with the Migration Toolkit for Runtimes Operator.

Prerequisites

  • 6 vCPUs, 8 GB RAM, and 40 GB persistent storage.

  • One or more projects in which you can install the web console.

    Important

    Do not install the web console in a default project.

  • cluster-admin privileges to install the Migration Toolkit for Runtimes Operator.
  • project-admin-user privileges to install the web console application in a project.

Configuring Red Hat Single Sign-on (SSO)

You must decide at installation time whether the web console requires authentication. If it does, you must first install and configure Red Hat SSO and input some RH SSO settings when instantiating the MTR Operator.

Note

Authentication can not be added or removed after installation.

  1. Open the Red Hat SSO administration console.
  2. Add a realm named windup.
  3. In the realm, create a client named windup-web.

  4. Check that Access Type is set to public. Set Valid Redirect URIs and Web Origins to *. Click *Save*.

    Note that after the MTR operator has been instantiated the Valid Redirect URIs and Web Origins fields have to be set to the secure-mtr-web-console route.

  5. Create a role named user.
  6. Create a user with any name.
  7. Set the credentials of the user, disable Temporary, and assign the role "user" to the user.

Installing the MTR Operator

  1. Log in to the OpenShift web console as a user with cluster-admin privileges.
  2. Click Operators → OperatorHub.
  3. Use the Search by keyword field to locate the Migration Toolkit for Runtimes Operator.
  4. Click Install.
  5. Select a project from the Installed Namespace list and click Install.
  6. Click Operators → Installed Operators to verify that the Operator is installed.

Installing the web console application

  1. Log in to the OpenShift web console as a user with project-admin-user privileges.
  2. Switch to the Developer perspective and click +Add.
  3. In the Add view, click Operator Backed.
  4. Click the Migration Toolkit for Runtimes Operator.
  5. Click Create.
  6. Review the application settings. If the web console requires authentication, input the RH SSO settings and click Create.
  7. In the Topology view, click the mtr-web-console application and then click the Resources tab.
  8. If authentication is required, set the RH SSO Valid Redirect URIs and Web Origins fields to the secure-mtr-web-console route.
  9. Click the secure-mtr-web-console route to open the web console in a new browser window.

2.2.1. Troubleshooting a web console installation on OpenShift

This section describes how to troubleshoot a web console installation on OpenShift Container Platform.

2.2.1.1. Downloading logs using the OpenShift console

You can download pod logs using the OpenShift console.

Procedure

  1. Open the OpenShift console and navigate to Applications → Pods.
  2. Click the mtr-web-console pod.
  3. Click Logs.
  4. Click Download to download and save a log.

2.2.1.2. Downloading logs using the CLI

You can download pod logs using the CLI.

Procedure

  1. Obtain the pod names: 

    $ oc get pods -n <project-name>

    The output resembles the following: 

    NAME                       READY     STATUS      RESTARTS   AGE
eap-builder-1-build        0/1       Completed   0          1d
mtr-postgresql-1-hfbdn     1/1       Running     0          1d
mtr-sso-1-build            0/1       Completed   0          1d
mtr-web-console-1-build    0/1       Completed   0          1d
mtr-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 log: 

    $ oc logs <pod>
    Note

    You can redirect the output to obtain a copy of the current log: 

    $ oc logs <pod> > ./<pod>.log

2.2.1.3. No route to host error

The No route to host error in the mtr-web-console-executor log indicates that the mtr-web-console-executor pod cannot connect to the mtr-web-console pod: 

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)]

This error occurs because the mtr-web-console-executor pod starts running before the mtr-web-console pod.

Check the mtr-web-console-executor log after the mtr-web-console pod has been running for a few minutes.

2.2.1.4. Resolving insufficient resources

The following conditions indicate insufficient resources:

  • The mtr-web-console pod is not running and the following error is displayed on the Events tab of the Pod Details screen in the OpenShift console: 

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

  • The mtr-web-console-deploy, mtr-web-console-executor-deploy, and mtr-web-console-postgresql-deploy pods time out and the following error is displayed in the logs: 

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

Procedure

  1. Install and run the cluster capacity tool to determine how many pods you can schedule.

  2. Change the load on the cluster resources by performing one of the following actions:

    • Increase the limit ranges or the resource quotas of your project.
    • Reduce the requested resources of your project. The web console requires a minimum of 4 vCPUs and 8 GB RAM.
    • Run fewer jobs.
  3. Redeploy the web console.

2.2.1.5. Reporting issues

MTR uses Jira as its issue tracking system. If you encounter an issue executing MTR, submit a Jira issue.