Updating

Signed-off-by: Andy Arnold <[email protected]>

docs/topics/mtr-about-console-guide.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: CONCEPT
+[id="about-console-guide_{context}"]
+= About the {WebNameTitle}
+
+This guide is for engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate or modernize Java applications or other components. It describes how to install and use the {WebName} to manage migration or modernization projects and analyze applications.

docs/topics/mtr-configuring-web-console-authentication-for-linux-windows-macos.adoc

@@ -0,0 +1,104 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="configuring-web-console-authentication-for-linux-windows-macos_{context}"]
+= Configuring authentication for the {WebName} on Linux, Windows, or macOS
+
+You can configure the {WebName} to require authentication for access. To  enable authentication, you have to install Red Hat Single Sign-On (SSO).
+
+[discrete]
+[id="enabling-authentication_{context}"]
+== Enabling authentication
+
+.Procedure
+
+. Adjust the port number that the Red Hat SSO server opens to avoid conflicts with the port that the {WebName} uses by entering the following:
++
+** For Linux and macOS:
++
+----
+$ ./standalone.sh -Djboss.socket.binding.port-offset=<offset_value>
+----
+** For Windows:
++
+----
+> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=<offset_value>
+----
+
+. Open the Red Hat SSO administration console from `\http://localhost:8180`:
+* Username: `admin`
+* Password: `admin`
+. Add a realm named *windup*.
+. In the realm, create a client named *windup-web*.
+. Check that *Access Type* is set to `public`.
+. Set *Valid Redirect URIs* to `\http://localhost:8080/windup-ui/*`.
+. Set *Web Origins* to `+*+` and click *Save*.
+. Create a role named *user*.
+. Create a user with any name.
+. Set the credentials of the user, disable *Temporary*, and assign the role "user" to the user.
+. Switch the {WebName} to *Authentication required* mode by doing the following:
+.. Export the following ENV variables:
+** For Linux and macOS:
++
+----
+export SSO_AUTH_SERVER_URL=http://localhost:8180/auth
+export SSO_REALM=windup
+export SSO_SSL_REQUIRED=EXTERNAL
+export SSO_CLIENT_ID=windup-web
+----
+** For Windows:
++
+----
+set SSO_AUTH_SERVER_URL=http://localhost:8180/auth
+set SSO_REALM=windup
+set SSO_SSL_REQUIRED=EXTERNAL
+set SSO_CLIENT_ID=windup-web
+----
++
+[NOTE]
+====
+Environment variables that are set by the `set` command in CMD are local, available to the current CMD session only. Use the Windows Control Panel to permanently set the environment variables.
+====
+
+.. Run the following script:
+** For Linux and macOS:
++
+----
+$ <MTR_HOME>/switch_to_authentication_required.sh
+----
+** For Windows:
++
+----
+C:\<MTR_HOME>\switch_to_authentication_required.bat
+----
+. Start the {WebName} by entering the following:
+** For Linux and macOS:
++
+----
+$ <MTR_HOME>/run_windup.sh
+----
+** For Windows:
++
+----
+C:\<MTR_HOME>\run_windup.bat
+----
+. Open the browser at `\http://localhost:8080/windup-ui`.
+
+[discrete]
+[id="disabling-authentication_{context}"]
+== Disabling authentication
+
+.Procedure
+. Run the following script:
+** For Linux and macOS:
++
+----
+$ <MTR_HOME>/switch_to_automatic_authentication.sh
+----
+** For Windows:
++
+----
+C:\<MTR_HOME>\switch_to_automatic_authentication.bat
+----

docs/topics/mtr-installing-web-console-on-openshift.adoc

@@ -0,0 +1,62 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="installing-web-console-on-openshift_{context}"]
+= Installing the {WebName} on {ocp-short} 4.11 and later
+
+You can install the {WebName} on {ocp-short} 4.11 and later versions with the {ProductName} Operator.
+
+.Prerequisites
+
+* 6 vCPUs, 8 GB RAM, and 40 GB persistent storage.
+* One or more projects in which you can install the {WebName}.
++
+[IMPORTANT]
+====
+Do not install the {WebName} in a default project.
+====
+
+* `cluster-admin` privileges to install the {DocInfoProductName} Operator.
+* `project-admin-user` privileges to install the {WebName} application in a project.
+
+.Configuring Red Hat Single Sign-on (SSO)
+
+You must decide at installation time whether the {WebName} 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.
+====
+
+. Open the Red Hat SSO administration console.
+. Add a realm named *windup*.
+. In the realm, create a client named *windup-web*.
+. Check that *Access Type* is set to `public`. Set *Valid Redirect URIs* and *Web Origins* to `\*`. Click *Save*.
++
+Note that after the {ProductShortName} operator has been instantiated, the *Valid Redirect URIs* and *Web Origins* fields have to be set to the secure-mtr-web-console route.
+. Create a role named *user*.
+. Create a user with any name.
+. Set the credentials of the user, disable *Temporary*, and assign the role "user" to the user.
+
+.Installing the {ProductShortName} Operator
+
+. Log in to the OpenShift web console as a user with `cluster-admin` privileges.
+. Click *Operators* -> *OperatorHub*.
+. Use the *Search by keyword* field to locate the *{DocInfoProductName}* Operator.
+. Click *Install*.
+. Select a project from the *Installed Namespace* list and click *Install*.
+. Click *Operators* -> *Installed Operators* to verify that the Operator is installed.
+
+.Installing the {WebName} application
+
+. Log in to the OpenShift web console as a user with `project-admin-user` privileges.
+. Switch to the *Migration* perspective and click *+Add*.
+. In the *Add* view, click *Operator Backed*.
+. Click the *{DocInfoProductName}* Operator.
+. Click *Create*.
+. Review the application settings. If the {WebName} requires authentication, input the RH SSO settings and click *Create*.
+. In the *Topology* view, click the `mtr-web-console` application and then click the *Resources* tab.
+. If authentication is required, set the RH SSO *Valid Redirect URIs* and *Web Origins* fields to the secure-mtr-web-console route.
+. Click the `secure-mtr-web-console` route to open the {WebName} in a new browser window.

docs/topics/mtr-proc_web-downloading-logs-cli.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="proc_web-downloading-logs-cli_{context}"]
+= Downloading logs using the CLI
+[role="_abstract"]
+
+You can download pod logs using the CLI.
+
+.Procedure
+
+. Obtain the pod names:
++
+----
+$ oc get pods -n <project-name>
+----
++
+The output resembles the following:
++
+[source,terminal,subs="attributes+"]
+----
+NAME                       READY     STATUS      RESTARTS   AGE
+eap-builder-1-build        0/1       Completed   0          1d
+{LC_PSN}-postgresql-1-hfbdn     1/1       Running     0          1d
+{LC_PSN}-sso-1-build            0/1       Completed   0          1d
+{LC_PSN}-web-console-1-build    0/1       Completed   0          1d
+{LC_PSN}-web-console-1-vt7s5    1/1       Running     1          1d
+sso-1-wjl2n                1/1       Running     1          1d
+----
+
+. 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
+----
+====

docs/topics/mtr-web-adding-global-custom-labels.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="web-adding-global-custom-labels_{context}"]
+= Adding global custom labels
+
+{ProductShortName} includes a preconfigured set of global labels, which apply to all projects.
+
+You can define your own custom global labels.
+
+.Procedure
+
+. In the {WebName}, click *Labels configuration*.
+. Click *Add label*.
+. To upload a labelset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*.
++
+A labelset file must have a `.windup.label.xml` extension. The uploaded file is stored on the {ProductShortName} server.
++
+. To register the server path of a labelset file, click the *Server path* tab, enter the *Labels* path, and click *Save*.
++
+Registering the server path ensures that the {ProductShortName} server always uses the latest version of the labelset files.
++
+The *Custom labels* list displays the labels.

docs/topics/mtr-web-adding-global-custom-rules.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="web-adding-global-custom-rules_{context}"]
+= Adding global custom rules
+
+{ProductShortName} includes a preconfigured set of global rules, which apply to all projects.
+
+You can define your own custom global rules.
+
+For information on writing custom {ProductShortName} rules, see the {ProductShortName} link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_].
+
+.Procedure
+
+. In the {WebName}, click *Rules configuration*.
+. Click *Add rules*.
+. To upload a ruleset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*.
++
+A ruleset file must have a `.windup.xml` extension. The uploaded file is stored on the {ProductShortName} server.
++
+. To register the server path of a ruleset file, click the *Server path* tab, enter the *Rules* path, and click *Save*.
++
+Registering the server path ensures that the {ProductShortName} server always uses the latest version of the ruleset files.
++
+The *Custom rules* list displays the rules.

docs/topics/mtr-web-create-project.adoc

@@ -0,0 +1,108 @@
+// Module included in the following assemblies:
+//
+// * docs/web-console-guide/master.adoc
+
+:_content-type: PROCEDURE
+[id="web-create-project_{context}"]
+= Creating a project
+
+You can create a project in the {WebName} with the *Create project* wizard.
+
+.Procedure
+
+. In the {WebName}, click *Projects*.
+. Click *Create project*.
+. Enter a unique name for the project, an optional description, and click *Next*.
++
+. To upload applications, click the *Upload* tab, click *Browse*, select the application files you want to upload, and click *Close*.
++
+Uploading applications stores them directly on the {ProductShortName} server.
+
+. To register a server path, click the *Server path* tab and enter the *Server-side path* of the application in the field.
++
+Registering the server path of an application ensures that {ProductShortName} always uses the latest version.
+. Click *Next*.
+. Click one or more transformation targets.
++
+image::web-console-transformation-targets.png[Transformation targets]
+. Click *Next*.
+. Select packages and click *>* to include them in the analysis.
+. Click *Next*.
++
+. If you want to add a custom rule, click *Add rule*.
++
+See the link:{ProductDocRulesGuideURL}[{RulesDevBookName}] for more information.
+
+* To upload a ruleset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*.
++
+A ruleset file must have a `.windup.xml` extension. The uploaded file is stored on the {ProductShortName} server.
++
+* To register the server path of a ruleset file, click the *Server path* tab, enter the *Rules* path, and click *Save*.
++
+Registering the server path ensures that the {ProductShortName} server always uses the latest version of the ruleset files.
++
+. Click *Next*.
++
+. If you want to add a custom label, click *Add label*.
+* To upload a labelset file, click the *Upload* tab, click *Browse*, select one or more files, and click *Close*.
++
+A labelset file must have a `.windup.label.xml` extension. The uploaded file is stored on the {ProductShortName} server.
++
+* To register a server path, click the *Server path* tab, enter the *Labels path* of the label files in the field, and click *Save*.
++
+Registering the server path ensures that the {ProductShortName} server always uses the latest version of the labelset files.
++
+. Click *Next*.
++
+. Review the following *Advanced options* and make any necessary changes:
+
+* *Target*
+* *Source*
+* *Exclude tags*: Rules with these tags are not processed.
+* *Additional classpath*: Enter a space-delimited list of additional `.jar` files or directories so that they are available for decompilation or other analysis.
+* *Application name*
+* *Mavenize group ID*
+* *Ignore path*: Enter a path for files to exclude from analysis.
+* *Export CSV*: Exports the report data as a CSV file.
+* *Export Summary*: Generates an `analysisSummary.json` export file in the output directory. The file contains analysis summary information for each application analyzed, including the number of incidents and story points by category, and all of the technology tags associated with the analyzed applications.
+* *Export reports zip*: Creates a `reports.zip` file in the output folder. The file contains the analysis output, typically, the reports. If requested, it can also contain the CSV export files.
+* *Disable Tattletale*: Disables generation of a Tattletale report for each application.
+* *Class Not Found analysis*: Enables analysis of Java files that are not available on the class path.
++
+[NOTE]
+====
+This option should not be used if some classes are unavailable for analysis.
+====
+
+* *Compatible Files report*: Generating a Compatible Files report might take a long time for large applications.
+* *Exploded app*: The input directory contains the unpackaged source files of an application.
+* *Keep work dirs*: Retains temporary files, for example, the graph database or extracted archive files, for debugging purposes.
+* *Skip reports*: HTML reports are not generated. Must be enabled if you enabled *Export CSV*.
+* *Allow network access*: Validates any XML files within the analyzed applications against their schema.
++
+[NOTE]
+====
+This option might reduce performance.
+====
+* *Mavenize*: Creates a Maven project directory structure based on the structure and content of the application.
+* *Source mode*: Indicates that the application files are raw source files, not compiled binaries. The sourceMode argument has been deprecated. There is no longer the need to specify it. MTR can intuitively process any inputs that are presented to it.  In addition, project source folders can be analyzed with binary inputs within the same analysis execution.
+* *Analyze known libraries*: Analyze known software artifacts embedded within your application.  By default, {ProductShortName} only analyzes application code.
++
+[NOTE]
+====
+This option might result in a longer execution time and a large number of migration issues being reported.
+====
+* *Transaction analysis*: [Tech Preview] Generates a Transactions report that displays the call stack, which executes operations on relational database tables. The Enable Transaction Analysis feature supports Spring Data JPA and the traditional `preparedStatement()` method for SQL statement execution. It does not support ORM frameworks, such as Hibernate.
++
+[NOTE]
+====
+Transaction analysis is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them
+in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+====
+* *Skip source code reports:* Adding this option skips generating a _Source code report_ when generating the application analysis report. Use this advanced option when concerned about source code information appearing in the application analysis.
+
+. Click *Next*.
++
+. Review your project and click *Save* or *Save and run*.
++
+The project is displayed in the *Projects* screen.