Merge pull request #173 from migtools/install-guide

mpershina · web-flow · commit 833fba9043a3 · 2025-09-29T11:25:59.000+02:00
[MTA 8.0.0] New Installing MTA UI and CLI title
diff --git a/assemblies/mta-install-title/assembly_installing-mta-cli.adoc b/assemblies/mta-install-title/assembly_installing-mta-cli.adoc
@@ -11,19 +11,18 @@ endif::[]
 ifdef::context[]
 [id="installing-mta-cli_{context}"]
 endif::[]
-= Installing {ProductShortName} command-line interface
+= Installing the {ProductName} command-line interface
 
 :context: installing-mta-cli
 
-You can install the {ProductFullName} command-line interface (CLI) on Linux, Windows, or macOS operating systems. 
+[role="_abstract"]
+You can install the {ProductFullName} command-line interface (CLI) on Linux, Windows, or macOS operating systems. You can also install the CLI for use with Docker on Windows. Note, however, that this is a Developer Preview feature only. 
 
-NOTE: You can also install the CLI for use with Docker on Windows. Note, however, that this is a Developer Preview feature only. 
+include::topics/mta-install/proc_installing-cli-zip.adoc[leveloffset=+1]
 
-include::topics/mta-cli/proc_installing-cli-zip.adoc[leveloffset=+1]
+include::topics/mta-install/proc_installing-mta-disconnected-environment.adoc[leveloffset=+1]
 
-include::topics/mta-cli/proc_installing-mta-disconnected-environment.adoc[leveloffset=+1]
-
-include::topics/mta-cli/proc_installing-cli-for-docker.adoc[leveloffset=+1]
+include::topics/mta-install/proc_installing-cli-for-docker.adoc[leveloffset=+1]
 
 
 ifdef::parent-context-of-installing-mta-cli[:context: {parent-context-of-installing-mta-cli}]
diff --git a/assemblies/mta-install-title/assembly_installing-mta-ui.adoc b/assemblies/mta-install-title/assembly_installing-mta-ui.adoc
@@ -0,0 +1,35 @@
+:_newdoc-version: 2.18.3
+:_template-generated: 2025-04-10
+
+ifdef::context[:parent-context-of-installing-mta-ui: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+ifndef::context[]
+[id="installing-mta-ui"]
+endif::[]
+ifdef::context[]
+[id="installing-mta-ui_{context}"]
+endif::[]
+= Installing the {ProductName} user interface
+:context: installing-mta-ui
+
+[role="_abstract"]
+You can install the {ProductFullName} user interface (UI) on all Red Hat OpenShift cloud services and Red Hat OpenShift self-managed editions. 			
+
+To create {ProductShortName} instances, you must first install the {ProductShortName} Operator. The {ProductShortName} Operator is a structural layer that manages resources deployed on OpenShift, such as database, front end, and back end, to automatically create an {ProductShortName} instance. 
+	
+include::topics/mta-install/ref_persistent-volume-requirements.adoc[leveloffset=+1]
+
+include::assembly_red-hat-build-of-keycloak.adoc[leveloffset=+1]
+
+include::topics/mta-install/proc_installing-mta-operator.adoc[leveloffset=+1]
+
+include::topics/mta-install/proc_creating-mta-instance.adoc[leveloffset=+1]
+
+include::topics/mta-install/ref_custom-resource-settings.adoc[leveloffset=+1]
+
+
+ifdef::parent-context-of-installing-mta-ui[:context: {parent-context-of-installing-mta-ui}]
+ifndef::parent-context-of-installing-mta-ui[:!context:]
+
diff --git a/assemblies/mta-install-title/assembly_intro-to-mta.adoc b/assemblies/mta-install-title/assembly_intro-to-mta.adoc
@@ -0,0 +1,36 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context-of-intro-to-mta: {context}]
+
+ifndef::context[]
+[id="intro-to-mta"]
+endif::[]
+ifdef::context[]
+[id="intro-to-mta_{context}"]
+endif::[]
+= Introduction to the {ProductName}
+
+:context: intro-to-mta
+
+[role="_abstract"]
+{ProductFullName} is a set of tools that you can use to accelerate large-scale application modernization efforts across hybrid cloud environments on Red Hat OpenShift. {ProductShortName} looks for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application. {ProductShortName} also generates a detailed report that evaluates a migration or modernization path. By using this report, you can estimate the effort required for large-scale projects and reduce the work involved. 
+
+By using the {ProductShortName}, you can perform the following tasks: 		
+
+* Use the {ProductShortName} extensive default questionnaire to assess your applications, or create your own custom questionnaire to estimate the difficulty, time, and other resources needed to prepare an application for containerization. You can use the results of an assessment for discussions between stakeholders to determine which applications are suitable for containerization.
+
+* Analyze applications by applying one or more sets of rules to each application. You can use these rules to determine which specific lines of the application must be modified before the application can be modernized. 				
+
+* Examine application artifacts, including project source directories and application archives, and produce an HTML report that highlights areas that require changes. 
+
+include::topics/mta-install/con_mta-features.adoc[leveloffset=+1]
+
+include::topics/mta-install/con_mta-rules.adoc[leveloffset=+1]
+
+include::topics/mta-install/con_mta-tools.adoc[leveloffset=+1]
+
+ifdef::parent-context-of-intro-to-mta[:context: {parent-context-of-intro-to-mta}]
+ifndef::parent-context-of-intro-to-mta[:!context:]
+
diff --git a/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc b/assemblies/mta-install-title/assembly_red-hat-build-of-keycloak.adoc
@@ -0,0 +1,30 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: ASSEMBLY
+
+ifdef::context[:parent-context-of-red-hat-build-of-keycloak: {context}]
+
+ifndef::context[]
+[id="red-hat-build-of-keycloak"]
+endif::[]
+ifdef::context[]
+[id="red-hat-build-of-keycloak_{context}"]
+endif::[]
+= Red Hat Build of Keycloak
+
+:context: red-hat-build-of-keycloak
+
+[role="_abstract"]
+Starting from version 7.3.0, {ProductShortName} uses the link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0[Red Hat Build of Keycloak (RHBK)] instance for user authentication and authorization. An RHBK instance is installed during the installation of the {ProductShortName} user interface. The {ProductShortName} Operator manages the RHBK instance and configures a dedicated realm with necessary roles and permissions. 
+
+You can use the {ProductShortName}-managed RHBK instance to perform advanced RHBK configurations, such as link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/user-storage-federation#adding_a_provider[adding a provider for User Federation] or link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/identity_broker[integrating identity providers]. 
+
+include::topics/mta-install/proc_accessing-rhbk-admin-console.adoc[leveloffset=+1]
+
+include::topics/mta-install/con_roles-personas-users-permissions.adoc[leveloffset=+1]
+
+
+
+ifdef::parent-context-of-red-hat-build-of-keycloak[:context: {parent-context-of-red-hat-build-of-keycloak}]
+ifndef::parent-context-of-red-hat-build-of-keycloak[:!context:]
+
diff --git a/assemblies/mta-install-title/topics b/assemblies/mta-install-title/topics
@@ -0,0 +1 @@
+../../topics/
diff --git a/docs/cli-guide/master.adoc b/docs/cli-guide/master.adoc
@@ -19,8 +19,6 @@ include::topics/mta-cli/con_intro-to-the-cli.adoc[leveloffset=+1]
 
 include::topics/mta-cli/ref_supported-migration-paths.adoc[leveloffset=+1]
 
-include::assemblies/cli-guide/assembly_installing-mta-cli.adoc[leveloffset=+1]
-
 include::assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc[leveloffset=+1]
 
 include::assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc[leveloffset=+1]
diff --git a/docs/install-guide/assemblies b/docs/install-guide/assemblies
@@ -0,0 +1 @@
+../../assemblies/
diff --git a/docs/install-guide/master-docinfo.xml b/docs/install-guide/master-docinfo.xml
@@ -0,0 +1,11 @@
+<title>{WebConsoleBookName}</title>
+<productname>{DocInfoProductName}</productname>
+<productnumber>{DocInfoProductNumber}</productnumber>
+<subtitle>Installing the Migration Toolkit for Applications user interface and command-line interface</subtitle>
+<abstract>
+    <para>By using the Migration Toolkit for Applications (MTA), you can accelerate large-scale application modernization efforts across hybrid cloud environments on Red Hat OpenShift. For example, you can inventory, assess, analyze, and manage applications for faster migration to OpenShift through the user interface at both the portfolio and application levels.</para>
+</abstract>
+<authorgroup>
+    <orgname>Red Hat Customer Content Services</orgname>
+</authorgroup>
+<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/docs/install-guide/master.adoc b/docs/install-guide/master.adoc
@@ -0,0 +1,31 @@
+:mta:
+include::topics/templates/document-attributes.adoc[]
+:_mod-docs-content-type: ASSEMBLY
+[id="installing-mta-title"]
+= Installing the Migration Toolkit for Applications
+
+:toc:
+:toclevels: 4
+:numbered:
+:imagesdir: topics/images
+:context: installing-mta-title
+:installing-mta-title:
+
+//Inclusive language statement
+include::topics/making-open-source-more-inclusive.adoc[leveloffset=+1]
+
+//Introduction to MTA
+include::assemblies/mta-install-title/assembly_intro-to-mta.adoc[leveloffset=+1]
+
+include::topics/mta-cli/ref_supported-migration-paths.adoc[leveloffset=+1]
+
+//Installing MTA
+include::assemblies/mta-install-title/assembly_installing-mta-ui.adoc[leveloffset=+1]
+
+include::assemblies/mta-install-title/assembly_installing-mta-cli.adoc[leveloffset=+1]
+
+include::topics/mta-cli/ref_contributing-to-mta-development.adoc[leveloffset=+1]
+
+
+
+:!installing-mta-title:
diff --git a/docs/install-guide/topics b/docs/install-guide/topics
@@ -0,0 +1 @@
+../topics/
diff --git a/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc b/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc
@@ -7,7 +7,10 @@
 [appendix,id="contributing-to-mta-development"]
 = Contributing to the {ProductShortName} project
 
-To help the {ProductName} cover most application constructs and server configurations, including yours, you can help with any of the following items:
+[role="_abstract"]
+You can help the {ProductName} to cover most application constructs and server configurations, including yours. 
+
+You can provide your help with any of the following items:
 
 * Send an email to jboss-migration-feedback@redhat.com and let us know what {ProductShortName} migration rules must cover.
 * Provide example applications to test migration rules.
diff --git a/docs/topics/mta-cli/ref_supported-migration-paths.adoc b/docs/topics/mta-cli/ref_supported-migration-paths.adoc
@@ -4,9 +4,12 @@
 :_mod-docs-content-type: REFERENCE
 
 [id="supported-migration-paths_{context}"]
-= Supported {ProductShortName} migration paths
+= Supported {ProductName} migration paths
 
-You can run the {ProductFullName} analysis to assess your applications' suitability for migration to multiple target platforms. {ProductShortName} supports the following migration paths:
+[role="_abstract"]
+You can use the {ProductFullName} to assess your applications' suitability for migration to multiple target platforms. 
+
+{ProductShortName} supports the following migration paths:
 
 .Supported Java migration paths
 [width="99%",cols="19%,10%,10%,10%,10%,10%,10%,10%,10%",options="^,header"]
diff --git a/docs/topics/mta-install/con_mta-features.adoc b/docs/topics/mta-install/con_mta-features.adoc
@@ -0,0 +1,21 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: CONCEPT
+
+[id="mta-features_{context}"]
+= {ProductShortName} features
+
+[role="_abstract"]
+{ProductFullName} provides the many features that simplify upgrades with multiple migration paths. 
+
+
+{ProductShortName} brings the following benefits for application analysis and assessment: 	
+
+* *Application inventory and assessment modules* to assist organizations in managing, classifying, and tagging their applications while assessing application suitability for deployment in containers, including flagging potential risks for migration strategies.	
+* *Full integration with source code and binary repositories* to automate the retrieval of applications for analysis along with proxy integration, including HTTP and HTTPS proxy configuration managed in the user interface. 					
+* *Improved analysis capabilities* with new analysis modes, including source and dependency modes that parse repositories to gather dependencies and add these dependencies to the overall scope of the analysis. You can also use a simplified user experience to configure the analysis scope, including open source libraries. 		
+* *Enhanced Role-Based Access Control (RBAC)* powered by link:https://access.redhat.com/products/red-hat-build-of-keycloak[Red Hat build of Keycloak] to define new differentiated personas (administrator, architect, and migrator) with different permissions to suit the needs of each user, including credentials management for multiple credential types. 					
+* *Administration perspective* to provide tool-wide configuration management for administrators. 					
+* *Support for Red Hat OpenShift on AWS (ROSA)* introduced in {ProductShortName} version 7.0.0. 		
+* *Support for Azure Red Hat OpenShift (ARO)* introduced in version MTA 7.0.0. 	
+* *Support for analyzing different languages* introduced in {ProductShortName} version 7.1.0.
diff --git a/docs/topics/mta-install/con_mta-rules.adoc b/docs/topics/mta-install/con_mta-rules.adoc
@@ -0,0 +1,37 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: CONCEPT
+
+[id="mta-rules_{context}"]
+= {ProductShortName} rules
+
+[role="_abstract"]
+The {ProductFullName} contains rule-based migration tools (analyzers) that you can use to analyze the application user interfaces (APIs), technologies, and architectures used by the applications you plan to migrate. 
+
+{ProductShortName} analyzer rules use the following rule pattern: 
+
+----
+when(condition)
+ message(message)
+ tag(tags)
+----
+
+You can use the {ProductShortName} rules internally to perform the following tasks: 			
+
+* Extract files from archives. 					
+* Decompile files. 					
+* Scan and classify file types. 					
+* Analyze XML and other file content. 					
+* Analyze the application code. 					
+* Build the reports. 					
+
+{ProductShortName} builds a data model based on the rule execution results and stores component data and relationships in a graph database. This database can then be queried and updated as required by the migration rules and for reporting purposes. 			
+
+[NOTE]
+====
+You can create your own custom analyzer rules. You can use custom rules to identify the use of custom libraries or other components that might not be covered by the provided standard migration rules. 				
+
+For instructions on how to write custom rules, see link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/rules_development_guide/index[Rules Development Guide]. 
+====
+
+
diff --git a/docs/topics/mta-install/con_mta-tools.adoc b/docs/topics/mta-install/con_mta-tools.adoc
@@ -0,0 +1,60 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: CONCEPT
+
+[id="mta-tools_{context}"]
+= {ProductShortName} tools
+
+[role="_abstract"]
+Different {ProductFullName} tools provide assistance in the various stages of your migration and modernization efforts. 		
+
+You can use the following {ProductShortName} tools for assessing and analyzing your applications: 		
+
+* *User interface (UI)*
++	
+By using the user interface for the {ProductName}, you can perform the following tasks: 
+
+** Assess the risks involved in containerizing an application for hybrid cloud environments on Red Hat OpenShift. 			
+** Analyze the changes that must be made in the code of an application to containerize the application.
+
++ 	
+For more information about using the MTA user interface, see link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/user_interface_guide/index[User Interface Guide]. 			
+   
+* *Command-line interface (CLI)*
++
+The CLI is a command-line tool in the {ProductName} that you can use to assess and prioritize migration and modernization efforts for applications. It provides numerous reports that highlight the analysis without using the other tools. The CLI includes a wide array of customization options. By using the CLI, you can tune {ProductShortName} analysis options or integrate with external automation tools.
++ 		
+For more information about using the CLI, see link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/cli_guide/index[CLI Guide]. 			
+	
+* *{ProductName} Operator*
++	
+By using the {ProductName} Operator, you can install the user interface on OpenShift Container Platform. 
++	
+For more information about the prerequisites for the MTA Operator installation, see link:https://access.redhat.com/support/policy/updates/openshift_operators[OpenShift Operator Life Cycles]. 				
+	
+* *IDE add-ons* 			
++
+You can migrate and modernize applications by using the {ProductName} add-ons for the following applications: 
++
+** Eclipse 					
+** Visual Studio Code, Visual Studio Codespaces, and Eclipse Che 	
+** IntelliJ IDEA, both the Community and Ultimate versions 
+
+
++
+You can use these add-ons to perform the following tasks: 
+
+** Analyze your projects by using customizable sets of rules. 			
+** Mark issues in the source code. 					
+** Fix the issues by using the provided guidance. 			
+** Use the automatic code replacement, if possible. 		
+
+
++
+For more information about using add-ons, see the following documentation:
+
+** link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/eclipse_plugin_guide/index[Eclipse Plugin Guide]
+** link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/intellij_idea_plugin_guide/index[IntelliJ IDEA Plugin Guide]
+** link:https://docs.redhat.com/en/documentation/migration_toolkit_for_applications/7.3/html/visual_studio_code_extension_guide/index[Visual Studio Code Extension Guide]
+
+
diff --git a/docs/topics/mta-install/con_roles-personas-users-permissions.adoc b/docs/topics/mta-install/con_roles-personas-users-permissions.adoc
@@ -0,0 +1,19 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: CONCEPT
+
+[id="roles-personas-users-permissions_{context}"]
+= Roles, personas, users, and permissions
+
+[role="_abstract"]
+The {ProductFullName} uses three roles, each corresponds to a persona. The roles are already defined in your RHBK instance. You do not need to create them. If you are an {ProductShortName} administrator, you can create users in your RHBK and assign each user one or more roles, one role per persona. 
+
+A user can have more than one role. Each role must correspond to a specific persona:
+
+* The `tackle-admin` role corresponds to the Administrator persona. The administrator has all the permissions that architects and migrators have, along with the ability to create some application-wide configuration parameters that other users can consume but cannot change or view, for example, Git credentials or Maven `settings.xml` files.
+
+* The `tackle-architect` role corresponds to the Architect persona. An architect is a technical lead for the migration project who can run assessments and can create and modify applications and information related to them. The architect cannot modify or delete sensitive information but can consume it. For example, the architect can associate an existing credential to the repository of a specific application. 	
+
+* The `tackle-migrator` role corresponds to the Migrator persona. A migrator is a user who can analyze applications but not create, modify, or delete them. 
+
+{ProductShortName} has two views, *Administration* and *Migration*. Only administrators can access the *Administration* view. Architects and migrators have no access to Administration view, they cannot even see it. Administrators can perform all actions supported by *Migration* view. Architects and migrators can see all elements of *Migration* view but their ability to perform actions in *Migration* view depends on the permissions granted to their role.
diff --git a/docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc b/docs/topics/mta-install/proc_accessing-rhbk-admin-console.adoc
@@ -0,0 +1,35 @@
+:_newdoc-version: 2.18.5
+:_template-generated: 2025-07-31
+:_mod-docs-content-type: PROCEDURE
+
+[id="accessing-rhbk-admin-console_{context}"]
+= Accessing the RHBK Admin Console
+
+[role="_abstract"]
+To perform advanced configurations to an RHBK instance, you must be logged in to the RHBK Admin Console.
+
+.Procedure
+
+. Retrieve your admin credentials:
++
+[subs="+quotes"]
+----
+$ *oc get secret mta-keycloak-rhbk -n openshift-mta -o json| jq -r '.data.password | @base64d'*
+----
++
+The admin credentials for RHBK are stored in the `mta-keycloak-rhbk` secret file in the namespace where you installed MTA. 	
+
+. Enter the following URL in your browser:
++
+[subs="+quotes,attributes"]
+----
+https://_<web_console_address>_/auth/admin
+----
+
+. Access the RHBK Admin Console by entering your credentials.
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/user-storage-federation#ldap[Configuring LDAP and Active Directory in RHBK]
+* link:https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.0/html/server_administration_guide/red_hat_build_of_keycloak_features_and_concepts[Red Hat Build of Keycloak features and concepts ]
+
diff --git a/docs/topics/mta-install/proc_creating-mta-instance.adoc b/docs/topics/mta-install/proc_creating-mta-instance.adoc
diff --git a/docs/topics/mta-install/proc_installing-cli-for-docker.adoc b/docs/topics/mta-install/proc_installing-cli-for-docker.adoc
diff --git a/docs/topics/mta-install/proc_installing-cli-zip.adoc b/docs/topics/mta-install/proc_installing-cli-zip.adoc
diff --git a/docs/topics/mta-install/proc_installing-mta-disconnected-environment.adoc b/docs/topics/mta-install/proc_installing-mta-disconnected-environment.adoc
diff --git a/docs/topics/mta-install/proc_installing-mta-operator.adoc b/docs/topics/mta-install/proc_installing-mta-operator.adoc
diff --git a/docs/topics/mta-install/ref_custom-resource-settings.adoc b/docs/topics/mta-install/ref_custom-resource-settings.adoc
diff --git a/docs/topics/mta-install/ref_persistent-volume-requirements.adoc b/docs/topics/mta-install/ref_persistent-volume-requirements.adoc
