diff --git a/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc b/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc new file mode 100644 index 00000000..f3501c16 --- /dev/null +++ b/assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc @@ -0,0 +1,46 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-03-17 + +ifdef::context[:parent-context-of-analyzing-applications-mta-cli: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="analyzing-applications-mta-cli"] +endif::[] +ifdef::context[] +[id="analyzing-applications-mta-cli_{context}"] +endif::[] += Analyzing Java applications with {ProductShortName} command-line interface + +:context: analyzing-applications-mta-cli + +Depending on your scenario, you can use the {ProductFullName} {CLINameTitle} to perform the following actions: + +* Run the analysis against a single application. +* Run the analysis against multiple applications: +** In {ProductShortName} versions earlier than 7.1.0, you can enter a series of `--analyze` commands, each against an application and each generating a separate report. For more information, see xref:analyzing-single-app-wth-mta-cli_analyzing-applications-mta-cli[Running the {ProductShortName} {CLINameTitle} against an application]. +** In {ProductShortName} version 7.1.0 and later, you can use the `--bulk` option to analyze multiple applications at once and generate a single report. Note that this feature is a Developer Preview feature only. For more information, see xref:analyzing-multiple-apps-with-mta-cli_analyzing-applications-mta-cli[Analyzing multiple applications]. + +[IMPORTANT] +==== +Starting from {ProductShortName} version 7.2.0, you can run the application analysis for Java applications in the containerless mode. Note that this option is set by default and is used automatically only if all requirements are met. For more information, see xref:running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in the containerless mode]. + +However, if you want to analyze applications in languages other than Java or, for example, use xref:performing-transformation_cli-guide[transformation commands], you still need to use containers. +==== + +{ProductShortName} CLI supports running source code and binary analysis by using `analyzer-lsp`. `analyzer-lsp` is a tool that evaluates rules by using language providers. + +include::topics/mta-cli/proc_analyzing-single-app-with-mta-cli.adoc[leveloffset=+1] + +include::topics/mta-cli/proc_analyzing-multiple-apps-with-mta-cli.adoc[leveloffset=+1] + +include::topics/mta-cli/proc_running-the-containerless-mta-cli.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_mta-cli-analyze-flags.adoc[leveloffset=+1] + +[role="_additional-resources"] + +ifdef::parent-context-of-analyzing-applications-mta-cli[:context: {parent-context-of-analyzing-applications-mta-cli}] +ifndef::parent-context-of-analyzing-applications-mta-cli[:!context:] + diff --git a/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc b/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc new file mode 100644 index 00000000..ecc20029 --- /dev/null +++ b/assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc @@ -0,0 +1,34 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-04-09 + +ifdef::context[:parent-context-of-analyzing-multi-language-applications: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="analyzing-nonjava-applications"] +endif::[] +ifdef::context[] +[id="analyzing-nonjava-applications_{context}"] +endif::[] += Analyzing applications written in languages other than Java with {ProductShortName} command-line interface + +:context: analyzing-nonjava-applications + +Starting from {ProductFullName} version 7.1.0, you can run the application analysis on applications written in languages other than Java. You can perform the analysis either of the following ways: + +* Select a supported language provider to run the analysis for. +* Overwrite the existing supported language provider with your own unsupported language provider, and then run the analysis on it. + + +IMPORTANT: Analyzing applications written in languages other than Java is only possible in container mode. You can use the containerless CLI only for Java applications. For more information, see xref:running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing an application in containerless mode]. + + +include::topics/mta-cli/proc_analyze-selected-provider.adoc[leveloffset=+1] + +include::topics/mta-cli/proc_analyze-unsupported-provider.adoc[leveloffset=+1] + + +ifdef::parent-context-of-analyzing-multi-language-applications[:context: {parent-context-of-analyzing-multi-language-applications}] +ifndef::parent-context-of-analyzing-multi-language-applications[:!context:] + diff --git a/assemblies/cli-guide/assembly_generating-assets.adoc b/assemblies/cli-guide/assembly_generating-assets.adoc new file mode 100644 index 00000000..bf9db15d --- /dev/null +++ b/assemblies/cli-guide/assembly_generating-assets.adoc @@ -0,0 +1,48 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-generating-assets: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="generating-assets"] +endif::[] +ifdef::context[] +[id="generating-assets_{context}"] +endif::[] += Generating platform assets for application deployment + +:context: generating-assets + +Starting from {ProductShortName} version 7.3.0, you can use the `discover` and `generate` commands in containerless mode to automatically generate the manifests needed to deploy a Cloud Foundry (CF) application in the {ocp-short}: + +* Use the `discover` command to generate the discovery manifest in the YAML format from the CF application manifest. The discovery manifest preserves the specifications found in the CF manifest that define the metadata, runtime, and platform configurations. +* Use the `generate` command to generate the deployment manifest for {ocp} deployments by using the discovery manifest. The deployment manifest is generated by using a templating engine, such as Helm, that converts the discovery manifest into a Kubernetes-native format. You can also use this command to generate non-Kubernetes manifests, such as a Dockerfile or a configuration file. + +:FeatureName: Generating platform assets for application deployment +include::topics/snippets/developer-preview-admonition.adoc[] + +.Benefits of generating deployment assets + +Generating deployment assets has the following benefits: + +* Generating the Kubernetes and non-Kubernetes deployment manifests. +* Generating deployment manifests by using familiar template engines, for example, Helm, that are widely used for Kubernetes deployments. +* Adhering to Kubernetes best practices when preparing the deployment manifest by using Helm templates. + + + +include::topics/mta-cli/proc_generating-discovery-manifest.adoc[leveloffset=+1] + +include::topics/mta-cli/proc_generating-deployment-manifest.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_discover-generate-command-options.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_assets-generation-example.adoc[leveloffset=+1] + + + +ifdef::parent-context-of-generating-assets[:context: {parent-context-of-generating-assets}] +ifndef::parent-context-of-generating-assets[:!context:] + diff --git a/assemblies/cli-guide/assembly_installing-mta-cli.adoc b/assemblies/cli-guide/assembly_installing-mta-cli.adoc new file mode 100644 index 00000000..24400697 --- /dev/null +++ b/assemblies/cli-guide/assembly_installing-mta-cli.adoc @@ -0,0 +1,31 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-03-14 + +ifdef::context[:parent-context-of-installing-mta-cli: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="installing-mta-cli"] +endif::[] +ifdef::context[] +[id="installing-mta-cli_{context}"] +endif::[] += Installing {ProductShortName} command-line interface + +:context: installing-mta-cli + +You can install the {ProductFullName} command-line interface (CLI) on Linux, Windows, or macOS operating systems. + +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-cli/proc_installing-cli-zip.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] + + +ifdef::parent-context-of-installing-mta-cli[:context: {parent-context-of-installing-mta-cli}] +ifndef::parent-context-of-installing-mta-cli[:!context:] + diff --git a/assemblies/cli-guide/assembly_performing-transformation.adoc b/assemblies/cli-guide/assembly_performing-transformation.adoc new file mode 100644 index 00000000..0abd9ca7 --- /dev/null +++ b/assemblies/cli-guide/assembly_performing-transformation.adoc @@ -0,0 +1,39 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-04-08 + +ifdef::context[:parent-context-of-performing-transformation: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="performing-transformation"] +endif::[] +ifdef::context[] +[id="performing-transformation_{context}"] +endif::[] += Performing a transformation with the {ProductShortName} command-line interface + + +:context: performing-transformation + +You can use transformation to perform the following actions: + +* Transform Java applications source code by using the `transform openrewrite` command. +* Convert XML rules to YAML rules by using the `transform rules` command. + +IMPORTANT: Performing transformation requires the container runtime to be configured. + + +include::topics/mta-cli/proc_transforming-application-source-code.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_available-openrewrite-recipes.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_openrewrite-command-options.adoc[leveloffset=+1] + +include::topics/mta-cli/proc_converting-xml-to-yaml.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_rules-command-options.adoc[leveloffset=+1] + +ifdef::parent-context-of-performing-transformation[:context: {parent-context-of-performing-transformation}] +ifndef::parent-context-of-performing-transformation[:!context:] + diff --git a/assemblies/cli-guide/assembly_reference-material.adoc b/assemblies/cli-guide/assembly_reference-material.adoc new file mode 100644 index 00000000..b6aeb74a --- /dev/null +++ b/assemblies/cli-guide/assembly_reference-material.adoc @@ -0,0 +1,34 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-reference-material: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="reference-material"] +endif::[] +ifdef::context[] +[id="reference-material_{context}"] +[appendix,id="reference-material"] +endif::[] += Reference material + +:context: reference-material + +The following is information that you might find useful when using the {ProductFullName} CLI. + +// {ProductShortName} Command-line Arguments +//include::topics/mta-cli-args.adoc[leveloffset=+2] + +// Added in 4.3.0: list of supported Tech Tags +include::topics/mta-cli/ref_mta-tech-tags.adoc[leveloffset=+1] + +// Rule Story Points +include::assembly_rule-story-points.adoc[leveloffset=+1] + + + +ifdef::parent-context-of-reference-material[:context: {parent-context-of-reference-material}] +ifndef::parent-context-of-reference-material[:!context:] + diff --git a/assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc b/assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc index ccf7505b..89e48be1 100644 --- a/assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc +++ b/assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc @@ -16,17 +16,11 @@ endif::[] After analyzing an application, you can access an analysis report to check the details of the application migration effort. -include::topics/proc_accessing-analysis-report.adoc[leveloffset=+1] +include::topics/mta-cli/proc_accessing-analysis-report.adoc[leveloffset=+1] -include::topics/ref_analysis-report-sections.adoc[leveloffset=+1] +include::topics/mta-cli/ref_analysis-report-sections.adoc[leveloffset=+1] -//// -[role="_additional-resources"] -== Additional resources - -* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide] -* xref:some-module_{context}[] -//// +include::topics/mta-cli/proc_reviewing-analysis-issues-and-incidents.adoc[leveloffset=+1] ifdef::parent-context-of-reviewing-analysis-reports[:context: {parent-context-of-reviewing-analysis-reports}] ifndef::parent-context-of-reviewing-analysis-reports[:!context:] diff --git a/assemblies/cli-guide/assembly_rule-story-points.adoc b/assemblies/cli-guide/assembly_rule-story-points.adoc new file mode 100644 index 00000000..34740bd8 --- /dev/null +++ b/assemblies/cli-guide/assembly_rule-story-points.adoc @@ -0,0 +1,29 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +ifdef::context[:parent-context-of-rule-story-points: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="rule-story-points"] +endif::[] +ifdef::context[] +[id="rule-story-points_{context}"] +endif::[] += Rule story points + +:context: rule-story-points + +_Story points_ are an abstract metric commonly used in Agile software development to estimate the level of effort required to implement a feature or change. + +The {ProductName} uses story points to express the level of effort needed to migrate particular application constructs, and the application as a whole. It does not necessarily translate to man-hours, but the value must be consistent across tasks. + +include::topics/mta-cli/ref_effort-level-estimation.adoc[leveloffset=+1] + +include::topics/mta-cli/ref_migration-tasks-categories.adoc[leveloffset=+1] + + +ifdef::parent-context-of-rule-story-points[:context: {parent-context-of-rule-story-points}] +ifndef::parent-context-of-rule-story-points[:!context:] + diff --git a/docs/cli-guide/master.adoc b/docs/cli-guide/master.adoc index 6d4aa016..049fa225 100644 --- a/docs/cli-guide/master.adoc +++ b/docs/cli-guide/master.adoc @@ -14,139 +14,29 @@ include::topics/templates/document-attributes.adoc[] //Inclusive language statement include::topics/making-open-source-more-inclusive.adoc[] -== Introduction -// About the {UserCLIBookName} -include::topics/about-cli-guide.adoc[leveloffset=+2] +include::topics/mta-cli/con_intro-to-the-cli.adoc[leveloffset=+1] -:FeatureName: .NET migration -include::topics/developer-preview-feature.adoc[] +include::topics/mta-cli/ref_supported-migration-paths.adoc[leveloffset=+1] -:FeatureName: Analyzing applications written in a language other than Java -include::topics/developer-preview-feature.adoc[] +include::assemblies/cli-guide/assembly_installing-mta-cli.adoc[leveloffset=+1] -// About {ProductName} -include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] +include::assemblies/cli-guide/assembly_analyzing-applications-mta-cli.adoc[leveloffset=+1] -include::topics/migration-paths.adoc[leveloffset=+3] +include::assemblies/cli-guide/assembly_analyzing-nonjava-applications.adoc[leveloffset=+1] -For more information about use cases and migration paths, see the link:https://developers.redhat.com/products/mta/use-cases[{ProductShortName} for developers] web page. - -// About the {CLINameTitle} -include::topics/about-cli.adoc[leveloffset=+2] - -== Installing and Running the CLI - -// Install the CLI -include::topics/installing-cli-tool.adoc[leveloffset=+2] - -// Install in disconnected environment -include::topics/installing-mta-disconnected-environment.adoc[leveloffset=+2] - -// CLI known issues -include::topics/cli-tool-known-issues.adoc[leveloffset=+3] - -[id="running-cli"] -=== Running the CLI - -Depending on your scenario, you can use the {ProductFullName} {CLINameTitle} to run the analysis in the following ways: - -* Run the analysis against a single application. -* Run the analysis against multiple applications: -** In {ProductShortName} versions earlier than 7.1.0, you can enter a series of `--analyze` commands, each against an application and each generating a separate report. For more information, see xref:mta-cli-run-single-app_cli-guide[Running the {ProductShortName} {CLINameTitle} against an application]. -** In {ProductShortName} 7.1.0 and later, you can use the `--bulk` option to analyze multiple applications at once and generate a single report. Note that this feature is a Developer Preview feature only. For more information, see xref:mta-cli-run-multiple-apps_cli-guide[Running the {ProductShortName} {CLINameTitle} against multiple applications and generating a single report (Developer Preview)]. - -//:FeatureName: Running the {CLINameTitle} against one or more applications -//include::topics/developer-preview-feature.adoc[] - -IMPORTANT: Starting from {ProductShortName} 7.2.0, you can run the application analysis in the containerless mode. Note that this option is set by default and is used automatically if all requirements are met. For more information, see xref:running-the-containerless-mta-cli_cli-guide[Running the containerless CLI]. - -// Run the CLI -include::topics/mta-cli-run-single-app.adoc[leveloffset=+3] - -include::topics/mta-cli-run-multiple-apps.adoc[leveloffset=+3] - -// Analyze application source code -include::topics/mta-cli-analyze.adoc[leveloffset=+3] - -include::topics/proc_running-the-containerless-mta-cli.adoc[leveloffset=+3] - -// Transform XML rules to YAML -include::topics/mta-cli-transform.adoc[leveloffset=+3] - -// Use OpenRewrite recipes -// include::topics/mta-using-openrewrite-recipes.adoc[leveloffset=+3] - -// Available OpenRewrite recipes -include::topics/available-openrewrite-recipes.adoc[leveloffset=+4] - -// Multi-language application analysis -include::topics/mta-cli-analyze-multi-lang-apps.adoc[leveloffset=+2] - -// Multi-language application analysis for the supported provider -include::topics/mta-cli-analyze-selected-provider.adoc[leveloffset=+3] - -// Multi-language application analysis for the unsupported provider -include::topics/mta-cli-analyze-unsupported-provider.adoc[leveloffset=+3] - -// Review the Reports include::assemblies/cli-guide/assembly_reviewing-analysis-reports.adoc[leveloffset=+1] -// Export the Report in CSV Format -// include::topics/csv-export.adoc[leveloffset=+1] - -// Mavenize Your Application -// include::topics/mavenize.adoc[leveloffset=+1] - -//Generating platform Assets for application deployment -include::topics/mta-cli-generate-assets.adoc[leveloffset=+1] - -//Generating the discovery manifest -include::topics/mta-cli-generate-discovery-manifest.adoc[leveloffset=+2] - -//Generating the deployment manifest -include::topics/mta-cli-generate-deployment-manifest.adoc[leveloffset=+2] - -//Generate asset for a Java application -include::topics/mta-cli-generate-deployment-asset-example.adoc[leveloffset=+2] - -// Optimize {ProductShortName} Performance -include::topics/mta-optimize-performance.adoc[leveloffset=+1] +include::assemblies/cli-guide/assembly_performing-transformation.adoc[leveloffset=+1] -// Configure {ProductShortName} to Exclude Files and Packages -// include::topics/mta-exclude-files-and-packages.adoc[leveloffset=+2] +include::assemblies/cli-guide/assembly_generating-assets.adoc[leveloffset=+1] -[appendix] -== Reference material - -// {ProductShortName} Command-line Arguments -include::topics/mta-cli-args.adoc[leveloffset=+2] - -// Added in 4.3.0: list of supported Tech Tags -include::topics/tech-tags.adoc[leveloffset=+2] - -// Rule Story Points -include::topics/about-story-points.adoc[leveloffset=+2] - -For more information on categorizing tasks, see link:{ProductDocRulesGuideURL}/rule_categories_rules-development-guide#rule_categories_rules-development-guide[Using custom rule categories]. - -=== Additional Resources - -// Get Involved -include::topics/get-involved.adoc[leveloffset=+3] - -// Important Links -include::topics/important-links.adoc[leveloffset=+3] - -// Report Issues with {ProductShortName} +// CLI known issues +include::topics/mta-cli/cli-tool-known-issues.adoc[leveloffset=+1] -==== Reporting issues +include::assemblies/cli-guide/assembly_reference-material.adoc[leveloffset=+1] -{ProductShortName} uses Jira as its issue tracking system. If you encounter an issue executing {ProductShortName}, submit a link:{JiraWindupURL}[Jira issue]. +include::topics/mta-cli/ref_contributing-to-mta-development.adoc[leveloffset=+1] -// ********************************** -// * Appendix: Revision Information * -// ********************************** -include::topics/templates/revision-info.adoc[] :!cli-guide: diff --git a/docs/topics/about-cli-guide.adoc b/docs/topics/about-cli-guide.adoc deleted file mode 100644 index 2c7c7c74..00000000 --- a/docs/topics/about-cli-guide.adoc +++ /dev/null @@ -1,9 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_content-type: CONCEPT -[id="about-cli-guide_{context}"] -= About the {UserCLIBookName} - -This guide is for engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate Java applications, .NET applications, or other components. In {ProductShortName} 7.1 and later, you can use {ProductShortName} to analyze applications written in languages other than Java. To run analysis on applications written in languages other than Java, add a custom rule set and do not specify a target language. This guide describes how to install and run the {CLIName}, review the generated reports, and take advantage of additional features. \ No newline at end of file diff --git a/docs/topics/about-story-points.adoc b/docs/topics/about-story-points.adoc deleted file mode 100644 index 8752009c..00000000 --- a/docs/topics/about-story-points.adoc +++ /dev/null @@ -1,64 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc -// * docs/maven-guide/master.adoc -// * docs/rules-development-guide/master.adoc - -:_content-type: CONCEPT -[id="about-story-points_{context}"] -= About rule story points - -== What are story points? - -_Story points_ are an abstract metric commonly used in Agile software development to estimate the _level of effort_ needed to implement a feature or change. - -The {ProductName} uses story points to express the level of effort needed to migrate particular application constructs, and the application as a whole. It does not necessarily translate to man-hours, but the value should be consistent across tasks. - -== How story points are estimated in rules - -Estimating the level of effort for the story points for a rule can be tricky. The following are the general guidelines {ProductShortName} uses when estimating the level of effort required for a rule. - -[cols="25%,15%,60%", options="header"] -|==== -|Level of Effort -|Story Points -|Description - -|Information -|0 -|An informational warning with very low or no priority for migration. - -|Trivial -|1 -|The migration is a trivial change or a simple library swap with no or minimal API changes. - -|Complex -|3 -|The changes required for the migration task are complex, but have a documented solution. - -|Redesign -|5 -|The migration task requires a redesign or a complete library change, with significant API changes. - -|Rearchitecture -|7 -|The migration requires a complete rearchitecture of the component or subsystem. - -|Unknown -|13 -|The migration solution is not known and may need a complete rewrite. -|==== - -== Task category - -In addition to the level of effort, you can categorize migration tasks to indicate the severity of the task. The following categories are used to group issues to help prioritize the migration effort. - -Mandatory:: The task must be completed for a successful migration. If the changes are not made, the resulting application will not build or run successfully. Examples include replacement of proprietary APIs that are not supported in the target platform. - -Optional:: If the migration task is not completed, the application should work, but the results may not be optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after your migration is completed. -//An example of this would be the upgrade of EJB 2.x code to EJB 3. - -Potential:: The task should be examined during the migration process, but there is not enough detailed information to determine if the task is mandatory for the migration to succeed. An example of this would be migrating a third-party proprietary type where there is no directly compatible type. - -Information:: The task is included to inform you of the existence of certain files. These may need to be examined or modified as part of the modernization effort, but changes are typically not required. -//An example of this would be the presence of a logging dependency or a Maven `pom.xml`. diff --git a/docs/topics/cli-tool-known-issues.adoc b/docs/topics/cli-tool-known-issues.adoc deleted file mode 100644 index 3fdc8643..00000000 --- a/docs/topics/cli-tool-known-issues.adoc +++ /dev/null @@ -1,45 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_content-type: PROCEDURE - -[id="cli-tool-known-issues_{context}"] -= {CLINameTitle} known issues - -.Limitations with Podman on Microsoft Windows - -The {CLINameTitle} is built and distributed with support for Microsoft Windows. - -However, when running any container image based on Red Hat Enterprise Linux 9 (RHEL9) or Universal Base Image 9 (UBI9), the following error can be returned when starting the container: - -[source,terminal] ----- -Fatal glibc error: CPU does not support x86-64-v2 ----- - -This error is caused because Red Hat Enterprise Linux 9 or Universal Base Image 9 container images must be run on a CPU architecture that supports `x86-64-v2`. - -For more details, see link:https://access.redhat.com/solutions/7057314[(Running Red Hat Enterprise Linux 9 (RHEL) or Universal Base Image (UBI) 9 container images fail with "Fatal glibc error: CPU does not support x86-64-v2")]. - -{CLINameTitle} runs the container runtime correctly. However, different container runtime configurations are not supported. - -Although unsupported, you can run {CLINameTitle} with *Docker* instead of *Podman*, which would resolve this issue. - -To achieve this, you replace the `PODMAN_BIN` path with the path to Docker. - -For example, if you experience this issue, instead of issuing: - -[source,terminal] ----- -PODMAN_BIN=/usr/local/bin/docker mta-cli analyze ----- - -You replace `PODMAN_BIN` with the path to Docker: - -[source,terminal] ----- -=/usr/local/bin/docker mta-cli analyze ----- - -While this is not supported, it would allow you to explore {CLINameTitle} while you work to upgrade your hardware or move to hardware that supports `x86_64-v2`. diff --git a/docs/topics/installing-mta-disconnected-environment.adoc b/docs/topics/installing-mta-disconnected-environment.adoc deleted file mode 100644 index 83ae2d39..00000000 --- a/docs/topics/installing-mta-disconnected-environment.adoc +++ /dev/null @@ -1,104 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_content-type: PROCEDURE -[id="installing-mta-disconnected-environment_{context}"] -= Installing {ProductShortName} on a disconnected environment - -When your system is in a disconnected environment, you can install the {ProductFullName} command-line interface (CLI) by performing the following actions: - -. Download the {ProductShortName} CLI images by using an external computer. -. Copy the downloaded images to the system you want to install the {ProductShortName} CLI on. - -IMPORTANT: The following procedure applies only to container mode. - - -NOTE: The analysis output in the disconnected environment usually results in less incidents because a dependency analysis does not run accurately without access to Maven. - - - - -On a connected device, first download and save the {ProductShortName} binary. Then download and save the Podman images, the {ProductShortName} CLI image and the provider image that you need. - -* Download the required {ProductShortName} CLI binary from the link:https://developers.redhat.com/products/mta/download[{ProductName} Red Hat Developer page]: -** CLI for Linux x86_64 -** CLI for Linux aarch64 -** CLI for MacOS x86_64 -** CLI for MacOS aarch64 -** CLI for Windows x86_64 -** CLI for Windows aarch64 - -* On a connected device, download and save the images. - -* Copy the binary to the disconnected device. - -* In addition, you must save and import the associated container images by using Podman. - -== Downloading the Podman images - -.Prerequisites - -* Podman installed. For more information, see link:https://podman.io/[Podman]. - -.Procedure - -. Use Podman to authenticate to link:registry.redhat.io[registry.redhat.io]: -+ -[source,terminal] ----- -$ podman login registry.redhat.io ----- - -. Enter your username and then your password for registry.redhat.io: -+ -[source,terminal] ----- -Username: -Password: ----- -+ -You should see the following output: -+ -[source,terminal] ----- -Login Succeeded! ----- - -. Use Podman to pull the image from the registry: -+ -[source,terminal] ----- -$ podman pull registry.redhat.io/mta/mta-cli-rhel9:7.1.0 ----- - -. Use Podman to pull the provider image that you need from the registry: - -.. For Java, run: -+ -[source,terminal] ----- -$ podman pull registry.redhat.io/mta/mta-java-external-provider-rhel9:7.1.0 ----- -.. For .NET, run: -+ -[source,terminal] ----- -$ podman pull registry.redhat.io/mta/mta-dotnet-external-provider-rhel9:7.1.0 ----- - -. Save the images: -+ -[source,terminal] ----- -$ podman save -o ----- - -. Copy the `.image` file and the binary onto a USB or directly to the file system of the disconnected device. - -. On the disconnected device, run -+ -[source,terminal] ----- -$ podman load --input ----- diff --git a/docs/topics/mta-cli-analyze-selected-provider.adoc b/docs/topics/mta-cli-analyze-selected-provider.adoc deleted file mode 100644 index 71149f2a..00000000 --- a/docs/topics/mta-cli-analyze-selected-provider.adoc +++ /dev/null @@ -1,32 +0,0 @@ -:_newdoc-version: 2.18.3 -:_template-generated: 2024-07-25 -:_mod-docs-content-type: PROCEDURE - -[id="selecting-language-providers-for-analysis_{context}"] -= Analyzing a multi-language application for the selected supported language provider - -When analyzing a multi-language application with {ProductFullName} {CLINameTitle}, you can explicitly set a supported language provider according to your application language to run the analysis for. - - -.Prerequisites - -* You are running the latest version of {ProductShortName} {CLINameTitle}. - - -.Procedure - -. List language providers supported for the analysis: -+ -[source,terminal,subs="attributes+"] ----- -$ mta-cli analyze --list-providers ----- - -. Run the application analysis for the selected language provider: -+ -[source,terminal,subs="attributes+"] ----- -$ mta-cli analyze --input <_path_to_the_source_repository_> --output <_path_to_the_output_directory_> --provider <_language_provider_> --rules <_path_to_custom_rules_> ----- -+ -Note that if you do not set the `--provider` option, the analysis might fail because it detects unsupported providers. The analysis will complete without `--provider` only if all discovered providers are supported. \ No newline at end of file diff --git a/docs/topics/mta-cli-generate-assets.adoc b/docs/topics/mta-cli-generate-assets.adoc deleted file mode 100644 index 1fd269d8..00000000 --- a/docs/topics/mta-cli-generate-assets.adoc +++ /dev/null @@ -1,27 +0,0 @@ -:_newdoc-version: 2.18.3 -:_template-generated: 2024-07-30 -:_mod-docs-content-type: CONCEPT - -[id="mta-cli-generate-assets_{context}"] -= Generating platform assets for application deployment - -Starting from {ProductShortName} 7.3.0, you can run the `discover` and `generate` commands in the containerless {ProductShortName} {CLIName}. The commands automatically generate the manifests needed to deploy a Cloud Foundry (CF) application in the {ocp-short}. - -* `Discover` command: Generates the discovery manifest in the YAML format from the CF application manifest. The discovery manifest preserves the specifications found in the CF manifest that define the metadata, runtime, and platform configurations. -* `Generate` command: Generates the deployment manifest for {ocp} deployments by using the discovery manifest. The deployment manifest is generated by using a templating engine such as Helm that converts the discovery manifest into a Kubernetes-native format. You can also use this command to generate non-Kubernetes manifests such as a Dockerfile or a configuration file. - -.Benefits of generating deployment assets by using the {ProductShortName} {CLIName} -* Extending the {ProductShortName} {CLIName} to generate the Kubernetes and non-Kubernetes deployment manifests. -* Generating deployment manifests using familiar template engines like Helm that are widely used for Kubernetes deployments. -* Adhering to Kubernetes best practices when preparing the deployment manifest using Helm templates. - -:FeatureName: Generating platform assets for application deployment -include::developer-preview-feature.adoc[] - -[id="support-matrix_{context}"] -== Support matrix - -* Source platform: Cloud Foundry (v3) -* Target platform: {ocp-short} -* CLI tool: {ProductShortName} {CLIName} 7.3.0 -* Status: Developer preview in 7.3.0 diff --git a/docs/topics/mta-cli-generate-deployment-manifest.adoc b/docs/topics/mta-cli-generate-deployment-manifest.adoc deleted file mode 100644 index a2d7e151..00000000 --- a/docs/topics/mta-cli-generate-deployment-manifest.adoc +++ /dev/null @@ -1,79 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_mod-docs-content-type: PROCEDURE -[id="mta-generate-deployment-manifest_{context}"] -= Generating the deployment manifest -Use the `generate` command to auto-generate the {ocp-full} deployment manifest for the Cloud Foundry (CF) application. Based on the Helm template that you provide, the command generates manifests such as a ConfigMap and non-Kubernetes manifests, such as a Dockerfile, for application deployment. - -.Prerequisites -* You generated a discovery manifest. -* You created a Helm template to capture required configuration for the {ocp} deployment. - -.Procedure -. Open the terminal application and navigate to the `<{ProductShortName}_HOME>/` directory. -. To generate the deployment manifest as an output file: -+ -[source,terminal] ----- -$ ./{mta-cli} generate helm --chart-dir helm_sample \ ---input \ ---output-dir \ ----- -. Verify the ConfigMap. -+ -[source,terminal] ----- -$ ./{mta-cli} cd \ -$ cat configmap.yaml -$ cat Dockerfile ----- -. Verify the Dockerfile. -+ -[source,terminal] ----- -$ ./{mta-cli} cd \ -$ cat Dockerfile ----- - -[source,terminal,subs="attributes+"] ----- -Usage: -$ {mta-cli} generate [flags] ----- - -[source,terminal,subs="attributes+"] ----- -Usage: -$ {mta-cli} generate helm [flags] ----- - -.Commands and Flags for `generate` -[width="100%",cols="30%,30%,40%",options="header"] -|=== -|Commands | Flags| Description - -a|`generate` -a|`-h`, `--help` -a|Help for generate. - -.6+a|`generate helm` -a| -a|Generate the deployment manifest by using the Helm template. - -a|`--chart-dir` -a|Specify the directory that contains the Helm chart. - -a|`--input` -a|Specify the location of the < _discovery-manifest-name.yaml_ > to generate the deployment manifest. - -a|`--non-k8s-only` -a|Generate only non-Kubernetes templates such as a Dockerfile. - -a|`--output-dir` -a|Specify the location to which the deployment manifests are saved. - -a|`--set` -a|Overrides values of attributes in the discovery manifest with the key-value pair entered from the CLI. -|=== diff --git a/docs/topics/mta-cli-generate-discovery-manifest.adoc b/docs/topics/mta-cli-generate-discovery-manifest.adoc deleted file mode 100644 index 6f213a32..00000000 --- a/docs/topics/mta-cli-generate-discovery-manifest.adoc +++ /dev/null @@ -1,68 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_mod-docs-content-type: PROCEDURE -[id="mta-generate-discovery-manifest_{context}"] -= Generating the discovery manifest -Use the `discover` command to generate the discovery manifest for the Cloud Foundry (CF) application. The discovery manifest preserves configurations such as application properties, resource allocations, environment variables, and service bindings found in the CF manifest. - -.Prerequisites -* You installed {ProductShortName} {CLIName} 7.3.0. -* You have a CF application manifest as a yaml file. - -.Procedure -. Open the terminal application and navigate to the `<{ProductShortName}_HOME>/` directory. - -. To list supported platforms for the discovery process: -+ -[source,terminal] ----- -$ ./{mta-cli} discover --list-platforms ----- - -. To generate the discovery manifest for a CF application as an output file: -+ -[source,terminal] ----- -$ ./{mta-cli} discover cloud-foundry \ ---input \ ---output \ ----- - -[source,terminal,subs="attributes+"] ----- -Usage: -$ {mta-cli} discover [flags] ----- - -[source,terminal,subs="attributes+"] ----- -Usage: -$ {mta-cli} discover cloud-foundry [flags] ----- - -.Commands and Flags for `discover` -[width="100%",cols="30%,30%,40%",options="header"] -|=== -|Commands | Flags| Description - -.2+a|`discover` -a|`-h`, `--help` -a|Help for discover. - - -a|`--list-platforms` -a|List supported platforms for the discovery process. - - -.3+a|`discover cloud-foundry` -a| -a|Discover Cloud Foundry applications. - -a|`--input` -a|Specify the location of the < _app-manifest-name.yaml_ > to discover the application configurations. - -a|`--output` -a|Specify the location to save the < _discovery-manifest-name.yaml_ >. -|=== \ No newline at end of file diff --git a/docs/topics/mta-cli/con_intro-to-the-cli.adoc b/docs/topics/mta-cli/con_intro-to-the-cli.adoc new file mode 100644 index 00000000..3b8aa0be --- /dev/null +++ b/docs/topics/mta-cli/con_intro-to-the-cli.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: CONCEPT +[id="intro-to-the-cli_{context}"] += Introduction to the {ProductShortName} command-line interface + +The {ProductFullName} command-line interface (CLI) provides a comprehensive set of rules to assess the suitability of your applications for containerization and deployment on Red Hat OpenShift. By using the {ProductShortName} CLI, you can assess and prioritize migration and modernization efforts for applications written in different languages. For example, you can use {ProductShortName} to analyze applications written in the following languages: + +* Java +* Go +* .NET +* Node.js +* Python + +:FeatureName: Analyzing applications written in the .NET language +include::../snippets/developer-preview-admonition.adoc[] + +:FeatureName: Analyzing applications written in the Python and Node.js languages +include::../snippets/technology-preview-admonition.adoc[] + +The CLI provides numerous reports that highlight the analysis without using the other tools. You can use the CLI to customize {ProductShortName} analysis options or integrate with external automation tools. \ No newline at end of file diff --git a/docs/topics/proc_accessing-analysis-report.adoc b/docs/topics/mta-cli/proc_accessing-analysis-report.adoc similarity index 82% rename from docs/topics/proc_accessing-analysis-report.adoc rename to docs/topics/mta-cli/proc_accessing-analysis-report.adoc index 9db4df31..2f5d2efe 100644 --- a/docs/topics/proc_accessing-analysis-report.adoc +++ b/docs/topics/mta-cli/proc_accessing-analysis-report.adoc @@ -1,5 +1,5 @@ :_newdoc-version: 2.18.5 -:_template-generated: 2025-06-16 +:_template-generated: 2025-06-18 :_mod-docs-content-type: PROCEDURE [id="accessing-analysis-report_{context}"] @@ -12,17 +12,9 @@ When you run an application analysis, a report is generated in the output direct * Copy the path of the `index.html` file from the analysis output and paste it in a browser of your choice: + [subs="+quotes"] ----- +.... Report created: __/index.html Access it at this URL: file:///__/index.html ----- +.... + Alternatively, press *Ctrl* and click on the path of the `index.html` file. - - - - -[role="_additional-resources"] -.Additional resources -* xref:running-cli[Running the CLI] - diff --git a/docs/topics/mta-cli/proc_analyze-selected-provider.adoc b/docs/topics/mta-cli/proc_analyze-selected-provider.adoc new file mode 100644 index 00000000..ef99be43 --- /dev/null +++ b/docs/topics/mta-cli/proc_analyze-selected-provider.adoc @@ -0,0 +1,32 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2024-07-25 +:_mod-docs-content-type: PROCEDURE + +[id="analyze-selected-provider_{context}"] += Analyzing an application for the selected supported language provider + +You can explicitly set a supported language provider according to your application’s language to run the analysis for. + + +.Prerequisites + +* You have the latest version of {ProductShortName} CLI installed on your system. + + +.Procedure + +. List language providers supported for the analysis: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --list-providers* +.... + +. Run the application analysis for the selected language provider: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --input __ --output __ --provider __ --rules __* +.... ++ +IMPORTANT: Note that if you do not set the `--provider` option, the analysis might fail because it detects unsupported providers. The analysis will complete without `--provider` only if all discovered providers are supported. \ No newline at end of file diff --git a/docs/topics/mta-cli/proc_analyze-unsupported-provider.adoc b/docs/topics/mta-cli/proc_analyze-unsupported-provider.adoc new file mode 100644 index 00000000..debc3a1c --- /dev/null +++ b/docs/topics/mta-cli/proc_analyze-unsupported-provider.adoc @@ -0,0 +1,41 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2024-07-30 +:_mod-docs-content-type: PROCEDURE + +[id="analyze-unsupported-provider_{context}"] += Analyzing an application for an unsupported language provider + +You can run the analysis for an unsupported language provider. To do so, you must overwrite the existing supported language provider with your own unsupported language provider. + +IMPORTANT: You must create a configuration file for your unsupported language provider before overriding the supported provider. + + +.Prerequisites + +* You created a configuration file for your unsupported language provider, for example: ++ +.... +[ +{ +"name": "java", +"address": "localhost:14651" +"initConfig": [{ +"location": "", +"providerSpecificConfig": { +"bundles": "", +"jvmMaxMem": "2G", +}, +"analysisMode": "source-only" +}] +} +] +.... + +.Procedure + +* Override an existing supported language provider with your unsupported provider and run the analysis: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --provider-override __ --output __ --rules __* +.... \ No newline at end of file diff --git a/docs/topics/mta-cli/proc_analyzing-multiple-apps-with-mta-cli.adoc b/docs/topics/mta-cli/proc_analyzing-multiple-apps-with-mta-cli.adoc new file mode 100644 index 00000000..144821be --- /dev/null +++ b/docs/topics/mta-cli/proc_analyzing-multiple-apps-with-mta-cli.adoc @@ -0,0 +1,48 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-03-17 +:_mod-docs-content-type: PROCEDURE + +[id="analyzing-multiple-apps-with-mta-cli_{context}"] += Analyzing multiple applications + +You can use the {ProductFullName} {CLINameTitle} to perform an application analysis for multiple applications at once and generate a combined report. + +:FeatureName: Analyzing multiple applications +include::../snippets/developer-preview-admonition.adoc[] + +.Procedure + +. Run the analysis for multiple applications. ++ +IMPORTANT: You must enter one input per analyze command, but make sure to enter the same output directory for all inputs. ++ +For example, to analyze example applications `A`, `B`, and `C`, enter the following commands: + +.. For input `A`, enter: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --bulk --input __ --output __ --source __ --target __* +.... + +.. For input `B`, enter: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --bulk --input __ --output __ --source __ --target __* +.... + +.. For input `C`, enter: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --bulk --input __ --output __ --source __ --target __* +.... + +. Access the analysis report. {ProductShortName} generates a single report, listing all issues that must be resolved before the applications can be migrated. + +[role="_additional-resources"] +.Additional resources + +* xref:installing-cli-zip_installing-mta-cli[Installing the CLI by using a .zip file] +* xref:mta-cli-analyze-flags_analyzing-applications-mta-cli[The mta-cli analyze command options] \ No newline at end of file diff --git a/docs/topics/mta-cli/proc_analyzing-single-app-with-mta-cli.adoc b/docs/topics/mta-cli/proc_analyzing-single-app-with-mta-cli.adoc new file mode 100644 index 00000000..20dc0a0d --- /dev/null +++ b/docs/topics/mta-cli/proc_analyzing-single-app-with-mta-cli.adoc @@ -0,0 +1,65 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-03-17 +:_mod-docs-content-type: PROCEDURE + +[id="analyzing-single-app-wth-mta-cli_{context}"] += Analyzing a single application + +You can use the {ProductFullName} CLI to perform an application analysis for a single application. + +NOTE: Extracting the list of dependencies from compiled Java binaries is not always possible during the analysis, especially if the dependencies are not embedded within the binary. + +.Procedure + +. Optional: List available target technologies for an analysis: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --list-targets* +.... + +. Run the analysis: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --input __ --output __ --source __ --target _* +.... ++ +Specify the following arguments: + +* `--input`: An application to be evaluated. +* `--output`: An output directory for the generated reports. `mta-cli analyze` creates the following analysis reports: ++ +.... +./ +├── analysis.log +├── dependencies.yaml +├── output.yaml +├── shim.log +├── static-report +└── static-report.log +.... + +* `--source`: A source technology for the application migration, for example, `weblogic`. +* `--target`: A target technology for the application migration, for example, `eap8`. + +. Access the generated analysis report: + +.. In the output of the `mta-cli analyze` command, copy a path to the `index.html` analysis report file: ++ +[subs="+quotes"] +.... +Report created: __/index.html + Access it at this URL: file:///__/index.html +.... + +.. Paste the path to the browser of your choice. + ++ +Alternatively, press *Ctrl* and click on the path to the report file. + +[role="_additional-resources"] +.Additional resources + +* xref:installing-cli-zip_installing-mta-cli[Installing the CLI by using a .zip file] +* xref:mta-cli-analyze-flags_analyzing-applications-mta-cli[The mta-cli analyze command options] \ No newline at end of file diff --git a/docs/topics/mta-cli/proc_converting-xml-to-yaml.adoc b/docs/topics/mta-cli/proc_converting-xml-to-yaml.adoc new file mode 100644 index 00000000..ea71cdd2 --- /dev/null +++ b/docs/topics/mta-cli/proc_converting-xml-to-yaml.adoc @@ -0,0 +1,35 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-04-08 +:_mod-docs-content-type: PROCEDURE + +[id="converting-xml-to-yaml_{context}"] += Converting XML rules to YAML rules + +You can convert the {ProductShortName} XML rules to the `analyzer-lsp` YAML rules, which are easier to maintain, by using the `mta-cli transform rules` command. To convert the rules, the `rules` subcommand uses the `windup-shim` tool. + +NOTE: The `mta-cli analyze` converts also automatically converts XML rules to YAML rules. + +NOTE: `analyzer-lsp` is the tool that evaluates the rules for the language providers and determines rule matches. + + + +.Prerequisites + +* You have the Podman tool installed and running. +* If your system is in a disconnected environment, you copied Podman images to the file system of the disconnected device and uploaded these images to the local Podman. + + +.Procedure + +* Convert the XML rules to the YAML rules: + +[literal,subs="+quotes,verbatim,normal,normal"] +.... +$ *mta-cli transform rules --input=__ --output=__* +.... + +[role="_additional-resources"] +.Additional resources + +* xref:rules-command-options_performing-transformation[The rules command options] + diff --git a/docs/topics/mta-cli/proc_generating-deployment-manifest.adoc b/docs/topics/mta-cli/proc_generating-deployment-manifest.adoc new file mode 100644 index 00000000..07bc4eff --- /dev/null +++ b/docs/topics/mta-cli/proc_generating-deployment-manifest.adoc @@ -0,0 +1,52 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="generating-deployment-manifest_{context}"] += Generating a deployment manifest + +You can auto-generate the {ocp-full} deployment manifest for the Cloud Foundry (CF) application by using the `generate` command. Based on the Helm template that you provide, the command generates manifests, such as a ConfigMap, and non-Kubernetes manifests, such as a Dockerfile, for application deployment. + +.Prerequisites + +* You have Cloud Foundry (v3) as a source platform. +* You have {ocp-short} as a target platform. +* You installed {ProductShortName} {CLIName} version 7.3.0. +* You generated a discovery manifest. +* You created a Helm template with the required configuration for the {ocp} deployment. + + +.Procedure + +. Open the terminal application and navigate to the `<{ProductShortName}_HOME>/` directory. + +. Generate the deployment manifest as an output file: ++ +[subs="+quotes"] +---- +$ *mta-cli generate helm --chart-dir helm_sample \ +--input __ \ +--output-dir __ \* +---- + +. Verify the ConfigMap: ++ +[subs="+quotes"] +---- +$ *mta-cli cd __ \* +$ *cat configmap.yaml* +$ *cat Dockerfile* +---- +. Verify the Dockerfile: ++ +[subs="+quotes"] +---- +$ *mta-cli cd __ \* +$ *cat Dockerfile* +---- + +[role="_additional-resources"] +.Additional resources + +* xref:discover-generate-command-options_generating-assets[The discover and generate command options] diff --git a/docs/topics/mta-cli/proc_generating-discovery-manifest.adoc b/docs/topics/mta-cli/proc_generating-discovery-manifest.adoc new file mode 100644 index 00000000..8294f959 --- /dev/null +++ b/docs/topics/mta-cli/proc_generating-discovery-manifest.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_mod-docs-content-type: PROCEDURE +[id="generating-discovery-manifest_{context}"] += Generating a discovery manifest + +You can generate the discovery manifest for the Cloud Foundry (CF) application by using the `discover` command. The discovery manifest preserves configurations, such as application properties, resource allocations, environment variables, and service bindings found in the CF manifest. + +.Prerequisites + +* You have Cloud Foundry (v3) as a source platform. +* You have {ocp-short} as a target platform. +* You installed {ProductShortName} {CLIName} version 7.3.0. +* You have a CF application manifest as a YAML file. + +.Procedure + +. Open the terminal application and navigate to the `<{ProductShortName}_HOME>/` directory. + +. List the supported platforms for the discovery process: ++ +[subs="+quotes"] +---- +$ *mta-cli discover --list-platforms* +---- + +. Generate the discovery manifest for a CF application as an output file: ++ +[subs="+quotes"] +---- +$ *mta-cli discover cloud-foundry \ +--input __ \ +--output __\* +---- + +[role="_additional-resources"] +.Additional resources + +* xref:discover-generate-command-options_generating-assets[The discover and generate command options] diff --git a/docs/topics/mta-cli/proc_installing-cli-for-docker.adoc b/docs/topics/mta-cli/proc_installing-cli-for-docker.adoc new file mode 100644 index 00000000..1d1682c1 --- /dev/null +++ b/docs/topics/mta-cli/proc_installing-cli-for-docker.adoc @@ -0,0 +1,116 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-03-17 +:_mod-docs-content-type: PROCEDURE + +[id="installing-cli-for-docker_{context}"] += Installing the CLI for use with Docker on Windows + +To migrate applications built with .NET framework version 4.5 or later, on Microsoft Windows to cross-platform .NET 8.0, you must install the CLI for use with Docker on Windows. To do so, you must configure Docker to use Windows containers first. + +.Prerequisites + +* A host with Windows 11+ 64-bit version 21H2 or higher. + +* You downloaded the Docker Desktop for Windows installation program. For more details, see link:https://docs.docker.com/desktop/install/windows-install/[Install Docker Desktop on Windows]. + +.Procedure + +. Open a PowerShell with Administrator privileges. + +. Ensure Hyper-V is installed and enabled: ++ +[subs="+quotes"] +---- +PS C:\Users\> *Enable-WindowsOptionalFeature -Online ` + -FeatureName Microsoft-Hyper-V-All* +---- ++ +[subs="+quotes"] +---- +PS C:\Users\> *Enable-WindowsOptionalFeature -Online ` + -FeatureName Containers* +---- ++ +NOTE: You might need to reboot Windows for the change to take effect. + +. Install Docker Desktop on Windows. + +.. Run the installer by double-clicking the `Docker_Desktop_Installer.exe` file. ++ +By default, Docker Desktop is installed to the `C:\Program Files\Docker\Docker` path. + +.. Ensure that Docker will run Windows containers as the backend instead of Linux containers: + +... In the Windows task bar, right-click on the Docker icon. +... Click *Switch to Windows containers*. + +. In PowerShell, create a folder for {ProductShortName}: ++ +[subs="+quotes"] +---- +PS C:\Users\> *mkdir C:\Users\\MTA* +---- + +. Extract the `{ProductShortNameLower}-{ProductVersion}-cli-windows.zip` file to the `MTA` folder: ++ +[subs="+quotes"] +---- +PS C:\Users\> *cd C:\Users\\Downloads* +---- ++ +[subs="+quotes"] +---- +PS C:\Users\> *Expand-Archive ` + -Path "{ProductShortNameLower}-{ProductVersion}-cli-windows.zip" ` + -DestinationPath "C:\Users\\MTA"* +---- + +. Ensure that Docker is running Windows containers the `OS/Arch` is set to `windows/amd64`: ++ +[subs="+quotes"] +---- +PS C:\Users\> *docker version* +---- ++ +[subs="+quotes"] +---- +Client: + Version: 27.0.3 + API version: 1.46 + Go version: go1.21.11 + Git commit: 7d4bcd8 + Built: Sat Jun 29 00:03:32 2024 + OS/Arch: *windows/amd64* + Context: desktop-windows +Server: Docker Desktop 4.32.0 (157355) + Engine: + Version: 27.0.3 + API version: 1.46 (minimum version 1.24) + Go version: go1.21.11 + Git commit: 662f78c + Built: Sat Jun 29 00:02:13 2024 + OS/Arch: *windows/amd64* + Experimental: false +---- + +. Set the `CONTAINER_TOOL` environment variable to use Docker: ++ +[subs="+quotes"] +---- +PS C:\Users\> *$env:CONTAINER_TOOL="C:\Windows\system32\docker.exe"* +---- + +. Set the `DOTNET_PROVIDER_IMG` environment variable to use the upstream `dotnet-external-provider`: ++ +[subs="+quotes"] +---- +PS C:\Users\> *$env:DOTNET_PROVIDER_IMG="quay.io/konveyor/dotnet-external-provider:v0.5.0"* +---- + +. Set the `RUNNER_IMG` environment variable to use the upstream image: ++ +[subs="+quotes"] +---- +PS C:\Users\> *$env:RUNNER_IMG="quay.io/konveyor/kantra:v0.5.0"* +---- + diff --git a/docs/topics/mta-cli/proc_installing-cli-zip.adoc b/docs/topics/mta-cli/proc_installing-cli-zip.adoc new file mode 100644 index 00000000..a91b8da4 --- /dev/null +++ b/docs/topics/mta-cli/proc_installing-cli-zip.adoc @@ -0,0 +1,39 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-03-14 +:_mod-docs-content-type: PROCEDURE + +[id="installing-cli-zip_{context}"] += Installing the CLI by using a .zip file + +You can install the {ProductFullName} command-line interface (CLI) by using the downloadable `.zip` file available on the link:https://developers.redhat.com/products/mta/download[official {ProductShortName} download page]. + + +.Prerequisites + +* Red Hat Container Registry Authentication for `registry.redhat.io`. Red Hat distributes container images from `registry.redhat.io`, which requires authentication. For more details, see link:https://access.redhat.com/RegistryAuthentication[Red Hat Container Registry Authentication]. ++ +NOTE: This prerequisite is not applicable for the containerless mode. For more information, see xref:running-the-containerless-mta-cli_analyzing-applications-mta-cli[Analyzing applications in containerless mode]. + +* You installed Java Development Kit (JDK) version 17 or later. +* You set the `JAVA_HOME` environmental variable. +* You installed Maven version 3.9.9 or later with its binary added to the `$PATH` variable. + + + +.Procedure + +. Navigate to the link:{DevDownloadPageURL}[{ProductShortName} download page] and download one of the following operating system-specific CLI files or the `src` file: ++ +* {ProductShortNameLower}-{ProductVersion}-cli-linux-amd64.zip +* {ProductShortNameLower}-{ProductVersion}-cli-linux-arm64.zip +* {ProductShortNameLower}-{ProductVersion}-cli-darwin-amd64.zip +* {ProductShortNameLower}-{ProductVersion}-cli-darwin-arm64.zip +* {ProductShortNameLower}-{ProductVersion}-cli-windows-amd64.zip +* {ProductShortNameLower}-{ProductVersion}-cli-windows-arm64.zip +* {ProductShortNameLower}-{ProductVersion}-cli-src.zip + +. Extract the `.zip` file. `.zip` extracts the `mta-cli` binary, along with other required directories and files. + +. Move the `mta-cli` binary to your `$PATH` variable. ++ +NOTE: You can place the `mta-cli` binary in any folder that is included in the `$PATH` variable. Alternatively, you can add a folder that contains `mta-cli` to `$PATH`. This way, you do not need to specify a full path when using the CLI. diff --git a/docs/topics/mta-cli/proc_installing-mta-disconnected-environment.adoc b/docs/topics/mta-cli/proc_installing-mta-disconnected-environment.adoc new file mode 100644 index 00000000..4c91920e --- /dev/null +++ b/docs/topics/mta-cli/proc_installing-mta-disconnected-environment.adoc @@ -0,0 +1,77 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: PROCEDURE +[id="installing-mta-disconnected-environment_{context}"] += Installing the CLI on a disconnected environment + +When your system is in a disconnected environment, you can install the {ProductFullName} command-line interface (CLI) by performing the following actions: + +. Download the required images by using an external computer. +. Copying the downloaded images to the system you want to install {ProductShortName} CLI on. + +IMPORTANT: The following procedure applies only to container mode. + +NOTE: The analysis output in the disconnected environment usually results in fewer incidents because a dependency analysis does not run accurately without access to Maven. + +.Prerequisites + +* You downloaded the required {ProductShortName} CLI binary from the link:https://developers.redhat.com/products/mta/download[{ProductName} Red Hat Developer page]. +* You installed the Podman tool on your system. +* For the analysis of Java applications, you enabled container runtime usage by setting the `--run-local` flag to `false`: ++ +.... +--run-local=false +.... ++ +The analysis of non-Java applications runs in container mode by default. + + +.Procedure + +. On a connected device, perform the following steps: + +.. Authenticate to registry.redhat.io: ++ +[subs="+quotes"] +.... +$ *podman login registry.redhat.io* +.... + +.. Run the `mta-cli` binary file. The binary file pulls the required provider images. For example: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze* +.... ++ +IMPORTANT: This command only pulls the required images. For example, if you run a command that requires Java images, a .NET image will not be pulled. + +.. Display the image list: ++ +[subs="+quotes"] +.... +$ *podman images* +REPOSITORY TAG IMAGE ID CREATED SIZE +registry.redhat.io/mta/mta-generic-external-provider-rhel9 7.3.1 8b8d7fa14570 13 days ago 692 MB +registry.redhat.io/mta/mta-cli-rhel9 7.3.1 45422a12d936 13 days ago 1.6 GB +registry.redhat.io/mta/mta-java-external-provider-rhel9 7.3.1 4d6d0912a38b 13 days ago 715 MB +registry.redhat.io/mta/mta-dotnet-external-provider-rhel9 7.3.1 66ec9fc51408 13 days ago 1.27 GB +.... + +.. Save the images: ++ +[subs="+quotes"] +.... +$ *podman save __ -o __.image* +.... + +.. Copy the images onto a USB drive or directly to the file system of the disconnected device. + +. On the disconnected device, enter: ++ +[subs="+quotes"] +.... +$ *podman load --input __.image* +.... diff --git a/docs/topics/mta-cli/proc_reviewing-analysis-issues-and-incidents.adoc b/docs/topics/mta-cli/proc_reviewing-analysis-issues-and-incidents.adoc new file mode 100644 index 00000000..60cf73f5 --- /dev/null +++ b/docs/topics/mta-cli/proc_reviewing-analysis-issues-and-incidents.adoc @@ -0,0 +1,46 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-07-08 +:_mod-docs-content-type: PROCEDURE + +[id="reviewing-analysis-issues-and-incidents_{context}"] += Reviewing the analysis issues and incidents + +After an analysis is complete, you can review issues that might appear during an application migration. Each issue contains a list of files where a rule matched one or more times. These files include all the incidents within the issue. Each incident contains a detailed explanation of the issue and how to fix this issue. + +.Procedure + +. Open the analysis report. For more information, see xref:accessing-analysis-report_reviewing-analysis-reports[Accessing an analysis report]. +. Click *Issues*. +. Click on the issue you want to check. +. Under the *File* tab, click on a file to display an incident or incidents that triggered the issue. +. Display the incident message by hovering over the line that triggered the incident, for example: ++ +[subs="+quotes"] +.... +Use the Quarkus Maven plugin adding the following sections to the pom.xml file: + +io.quarkus.platform +3.1.0.Final + + + + +$ +quarkus-maven-plugin +$ +true + + + +build +generate-code +generate-code-tests + + + + + + +.... + + diff --git a/docs/topics/mta-cli/proc_running-the-containerless-mta-cli.adoc b/docs/topics/mta-cli/proc_running-the-containerless-mta-cli.adoc new file mode 100644 index 00000000..28c35e22 --- /dev/null +++ b/docs/topics/mta-cli/proc_running-the-containerless-mta-cli.adoc @@ -0,0 +1,59 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2024-11-15 +:_mod-docs-content-type: PROCEDURE + +[id="running-the-containerless-mta-cli_{context}"] += Analyzing an application in containerless mode + +Starting from {ProductShortName} 7.2.0, you can perform an application analysis for Java applications by using the {ProductShortName} CLI that does not require installation of a container runtime. + +[IMPORTANT] +==== +In {ProductShortName} 7.2.0 and later, containerless CLI is a default mode. To enable container runtime usage for the analysis of Java applications, you must set the `--run-local` flag to `false`: + +---- +--run-local=false +---- + +The analysis for other applications runs in the container mode automatically +==== + +.Prerequisites + +* You installed the {ProductShortName} CLI. For more information, see xref:installing-cli-zip_installing-mta-cli[Installing the CLI by using a .zip file]. +* You installed Java Development Kit (JDK) version 17 or later. +* If you use OpenJDK on Red Hat Enterprise Linux (RHEL) or Fedora, you installed the Java `devel` package. +* You installed Maven version 3.9.9 or later. +* The CLI assumes that a path to the `mvn` binary is correctly registered in the system variable. Therefore, ensure that you added `mvn` to the following variable: +** `Path` for Windows. +** `PATH` for Linux and macOS. +* You set the `JAVA_HOME` environmental variable. +* You set the `JVM_MAX_MEM` system variable. ++ +NOTE: If you do not set `JVM_MAX_MEM`, the analysis might hang because Java might require more memory than the default `JVM_MAX_MEM` value. + + +.Procedure + +. Optional: Display all `mta-cli analyze` command options: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --help* +.... + +. Run the application analysis: ++ +[subs="+quotes"] +.... +$ *mta-cli analyze --overwrite --input __ --output __ --target __* +.... ++ +NOTE: The `--overwrite` option overwrites the output folder if it exists. + + +[role="_additional-resources"] +.Additional resources + +* xref:installing-cli-zip_installing-mta-cli[Installing the CLI by using a .zip file] +* xref:mta-cli-analyze-flags_analyzing-applications-mta-cli[The mta-cli analyze command options] diff --git a/docs/topics/mta-cli/proc_transforming-application-source-code.adoc b/docs/topics/mta-cli/proc_transforming-application-source-code.adoc new file mode 100644 index 00000000..5632f608 --- /dev/null +++ b/docs/topics/mta-cli/proc_transforming-application-source-code.adoc @@ -0,0 +1,43 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-04-08 +:_mod-docs-content-type: PROCEDURE + +[id="transforming-application-source-code_{context}"] += Transforming applications source code + +To update Java libraries or frameworks, for example, `javax` or Spring Boot, you can transform Java application source code by using the `transform openrewrite` command. The `openrewrite` subcommand allows running `OpenRewrite` recipes on source code. + +NOTE: You can only use a single target to run the `transform overwrite` command. + + +.Prerequisites + +* You configured the container runtime. + +.Procedure + +. Display the available `OpenRewrite` recipes: ++ +[literal,subs="+quotes,verbatim,normal,normal"] +.... +$ *mta-cli transform openrewrite --list-targets* +.... + +. Transform the application source code: ++ +[literal,subs="+quotes,verbatim,normal,normal"] +.... +$ *mta-cli transform openrewrite --input=__ --target=__* +.... + + +.Verification + +* Inspect the target application source code `diff` to see the transformation. + + +[role="_additional-resources"] +.Additional resources + +* xref:available-openrewrite-recipes_performing-transformation[Available OpenRewrite recipes] +* xref:openrewrite-command-options_performing-transformation[The openrewrite command options] diff --git a/docs/topics/ref_analysis-report-sections.adoc b/docs/topics/mta-cli/ref_analysis-report-sections.adoc similarity index 73% rename from docs/topics/ref_analysis-report-sections.adoc rename to docs/topics/mta-cli/ref_analysis-report-sections.adoc index c8338177..5767b6b8 100644 --- a/docs/topics/ref_analysis-report-sections.adoc +++ b/docs/topics/mta-cli/ref_analysis-report-sections.adoc @@ -1,5 +1,5 @@ :_newdoc-version: 2.18.5 -:_template-generated: 2025-06-16 +:_template-generated: 2025-06-18 :_mod-docs-content-type: REFERENCE [id="analysis-report-sections_{context}"] @@ -7,26 +7,24 @@ The following are sections of an analysis report that are available after the application analysis is complete. These sections contain additional details about the migration of an application. -NOTE: You can only review the report for the current application. +NOTE: You can only review the report applicable to the current application. :FeatureName: Insights -include::snippets/technology-preview-admonition.adoc[] - - +include::../snippets/technology-preview-admonition.adoc[] .Analysis report sections [options="header"] |==== |Section|Description -|Dashboard|An overview of the incidents and total story points sorted by category. +|Dashboard|An overview of the incidents and total story points, sorted by category. |Issues|A concise summary of all issues and their details that require attention. |Dependencies|All Java-packaged dependencies found within the application. |Technologies|All embedded libraries grouped by functionality. Use this report to display the technologies used in each application. -|Insights|Information about a violation generated by a rule with zero effort. Issues are generated by general rules, whereas string tags are generated by tagging rules. String tags indicate the presence of a technology but do not show the code location. Insights contain the information about the technologies used in the application and their usage in the code. +|Insights|Information about a violation generated by a rule with zero effort. Issues are generated by general rules, whereas string tags are generated by the tagging rules. String tags indicate the presence of a technology but do not show the code location. Insights contain information about the technologies used in the application and their usage in the code. Insights do not impact the migration. For example, a rule searching for deprecated API usage in the code that does not impact the current migration but can be tracked and fixed when needed in the future. -Unlike with issues, you do not need to fix insights for a successful migration. They are generated by any rule that does not have a positive effort value and category assigned. They might have a message and a tag. +Unlike with issues, you do not need to fix insights for a successful migration. They are generated by any rule that does not have a positive effort value and category assigned. They might have a message and tag. |==== diff --git a/docs/topics/mta-cli-generate-deployment-asset-example.adoc b/docs/topics/mta-cli/ref_assets-generation-example.adoc similarity index 52% rename from docs/topics/mta-cli-generate-deployment-asset-example.adoc rename to docs/topics/mta-cli/ref_assets-generation-example.adoc index a0f1768c..f7190f60 100644 --- a/docs/topics/mta-cli-generate-deployment-asset-example.adoc +++ b/docs/topics/mta-cli/ref_assets-generation-example.adoc @@ -1,12 +1,12 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 -:_mod-docs-content-type: PROCEDURE -[id="mta-generate-deployment-asset-example_{context}"] -= Generating the discovery and deployment manifest example +:_mod-docs-content-type: REFERENCE -This example shows how to generate the discovery manifest and the deployment manifest of a Cloud Foundry (CF) Node.js application by using the `discover` and `generate` commands, respectively. +[id="assets-generation-example_{context}"] += Assets generation example + +The following is an example of generating discovery and deployment manifests of a Cloud Foundry (CF) Node.js application. For this example, the following files and directories are used: @@ -16,21 +16,23 @@ For this example, the following files and directories are used: * Deployment manifests: a ConfigMap and a Dockerfile * Output location of the deployment manifests: `newDir` -In this example, it is assumed that the `cf-nodejs-app.yaml` is located in the same directory as the {ProductShortName} {CLIName} binary. If the CF application manifest location is different, you can also enter the location path to the manifest as the `input`. +Assumed that the `cf-nodejs-app.yaml` is located in the same directory as the {ProductShortName} {CLIName} binary. If the CF application manifest location is different, you can also enter the location path to the manifest as the `input`. .Prerequisites + * You installed {ProductShortName} {CLIName} 7.3.0. -* You have a CF application manifest as a yaml file. -* You created a Helm template to capture the required configurations for the {ocp} deployment. +* You have a CF application manifest as a YAML file. +* You created a Helm template with the required configurations for the {ocp} deployment. .Procedure + . Open the terminal application and navigate to the `<{ProductShortName}_HOME>/` directory. . Verify the content of the CF Node.js application manifest: + -[source,terminal] +[subs="+quotes"] ---- -$ cat cf-nodejs-app.yaml +$ *cat cf-nodejs-app.yaml* name: cf-nodejs lifecycle: cnb buildpacks: @@ -40,20 +42,21 @@ memory: 512M instances: 1 random-route: true ---- -. To generate the discover manifest for the CF Node.js application: + +. Generate the discovery manifest: + -[source,terminal] +[subs="+quotes"] ---- -$ ./{mta-cli} discover cloud-foundry \ +$ *mta-cli discover cloud-foundry \ --input cf-nodejs-app.yaml \ ---output discover.yaml \ +--output discover.yaml \* ---- . Verify the content of the discover manifest: + -[source,terminal] +[subs="+quotes"] ---- -$ cat discover.yaml +$ *cat discover.yaml* name: cf-nodejs randomRoute: true timeout: 60 @@ -63,20 +66,20 @@ buildPacks: instances: 1 ---- -. To generate the deployment manifest in the `newDir` directory by using the `discover.yaml`: +. Generate the deployment manifest in the `newDir` directory by using the `discover.yaml` file: + -[source,terminal] +[subs="+quotes"] ---- -$ ./{mta-cli} generate helm \ +$ *mta-cli generate helm \ --chart-dir helm_sample \ ---input discover.yaml --output-dir newDir +--input discover.yaml --output-dir newDir* ---- -. Check the contents of the Dockerfile the `newDir` directory: +. Check the contents of the Dockerfile in the `newDir` directory: + -[source,terminal] +[subs="+quotes"] ---- -$ cat ./newDir/Dockerfile +$ *cat ./newDir/Dockerfile* FROM busybox:latest RUN echo "Hello cf-nodejs!" @@ -84,9 +87,9 @@ RUN echo "Hello cf-nodejs!" . Check the contents of the ConfigMap in the `newDir` directory: + -[source,terminal] +[subs="+quotes"] ---- -$ cat ./newDir/configmap.yaml +$ *cat ./newDir/configmap.yaml* apiVersion: v1 kind: ConfigMap metadata: @@ -100,22 +103,22 @@ data: INSTANCES: "1" ---- -. To override the `name` to `nodejs-app` and `INSTANCES` to `2` in the ConfigMap: +. In the ConfigMap, override the `name` to `nodejs-app` and `INSTANCES` to `2` : + -[source,terminal] +[subs="+quotes"] ---- -$ ./{mta-cli} generate helm \ +$ *mta-cli generate helm \ --chart-dir helm_sample \ --input discover.yaml --set name="nodejs-app" \ --set instances=2 \ ---output-dir newDir \ +--output-dir newDir \* ---- . Check the contents of the ConfigMap again: + -[source,terminal] +[subs="+quotes"] ---- -$ cat ./newDir/configmap.yaml +$ *cat ./newDir/configmap.yaml* apiVersion: v1 kind: ConfigMap metadata: @@ -127,4 +130,9 @@ data: - docker://my-registry-a.corp/nodejs - docker://my-registry-b.corp/dynatrace INSTANCES: "2" ----- \ No newline at end of file +---- + +[role="_additional-resources"] +.Additional resources + +* xref:discover-generate-command-options_generating-assets[The discover and generate command options] diff --git a/docs/topics/mta-cli/ref_available-openrewrite-recipes.adoc b/docs/topics/mta-cli/ref_available-openrewrite-recipes.adoc new file mode 100644 index 00000000..b1e8c298 --- /dev/null +++ b/docs/topics/mta-cli/ref_available-openrewrite-recipes.adoc @@ -0,0 +1,22 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-04-08 + +:_mod-docs-content-type: REFERENCE + +[id="available-openrewrite-recipes_{context}"] += Available OpenRewrite recipes + +The following are the `OpenRewrite` recipes that you can use for transforming application source code. + +.Available OpenRewrite recipes +[options="header"] +|==== +|Migration path|Purpose|The `rewrite.config` file location|Active recipes +|Java EE to Jakarta EE|Replace import of `javax` packages with equivalent `jakarta` packages. + +Replace `javax` artifacts, declared within `pom.xml` files, with the `jakarta` equivalents.|`__/rules/openrewrite/jakarta \ /javax/imports/rewrite.yml`|`org.jboss.windup.JavaxToJakarta` +|Java EE to Jakarta EE |Rename bootstrapping files.|`__/rules/openrewrite/jakarta \ /javax/bootstrapping/rewrite.yml`|`org.jboss.windup.jakarta.javax. \ BootstrappingFiles` +|Java EE to Jakarta EE |Transform the `persistence.xml` file configuration.|`__/rules/openrewrite/jakarta \ /javax/xml/rewrite.yml`|`org.jboss.windup.javax-jakarta. \ PersistenceXML` +|Spring Boot to Quarkus |Replace `spring.jpa.hibernate.ddl-auto` property within files matching `application*.properties`. |`__/rules/openrewrite/quarkus \ /springboot/properties/rewrite.yml`|`org.jboss.windup.sb-quarkus.Properties` +|==== + diff --git a/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc b/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc new file mode 100644 index 00000000..ceefbbea --- /dev/null +++ b/docs/topics/mta-cli/ref_contributing-to-mta-development.adoc @@ -0,0 +1,34 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +:_mod-docs-content-type: REFERENCE + +[id="contributing-to-mta-development_{context}"] +[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: + +* 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. +* Identify application components and problem areas that might be difficult to migrate: +** Write a short description of the problem migration areas. +** Write a brief overview describing how to solve the problem in migration areas. +* Try {ProductName} on your application. Make sure to report any issues you meet. +* Try {ProductName} on your application. Make sure to report any issues you meet.{ProductShortName} uses Jira as its issue tracking system. If you encounter an issue executing {ProductShortName}, submit a link:{JiraWindupURL}[Jira issue]. +* Contribute to the {ProductName} rules repository: +** Write a {ProductName} rule to identify or automate a migration process. +** Create a test for the new rule. ++ +For more information, see link:{ProductDocRulesGuideURL}[_{RulesDevBookName}_]. +* Contribute to the project source code: +** Create a core rule. +** Improve {ProductShortName} performance or efficiency. + + +[role="_additional-resources"] +.Additional resources + +* link:https://developer.jboss.org/en/windup[{ProductShortName} forums] +* link:https://issues.redhat.com/projects/MTA/issues/MTA-4961?filter=allopenissues[Jira issues tracker] +Any level of involvement is greatly appreciated! \ No newline at end of file diff --git a/docs/topics/mta-cli/ref_discover-generate-command-options.adoc b/docs/topics/mta-cli/ref_discover-generate-command-options.adoc new file mode 100644 index 00000000..3113deeb --- /dev/null +++ b/docs/topics/mta-cli/ref_discover-generate-command-options.adoc @@ -0,0 +1,57 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +:_mod-docs-content-type: REFERENCE + +[id="discover-generate-command-options_{context}"] += The discover and generate command options + +You can use the following options together with the `discover` or `generate` command to adjust the command behavior to your needs. + +.Options for `discover` and `generate` commands +[width="100%",cols="30%,30%,40%",options="header"] +|=== +| Command | Option | Description + +.2+a|`discover` +a|`-h`, `--help` +a|Display details for different command arguments. + + +a|`--list-platforms` +a|List the supported platforms for the discovery process. + + +.3+a|`discover cloud-foundry` +a| +a|Discover Cloud Foundry applications. + +a|`--input` +a|Specify the location of the __.yaml file to discover the application configurations. + +a|`--output` +a|Specify the location to save the __.yaml file. + +a|`generate` +a|`-h`, `--help` +a|Display details for different command arguments. + +.6+a|`generate helm` +a| +a|Generate a deployment manifest by using the Helm template. + +a|`--chart-dir` +a|Specify a directory that contains the Helm chart. + +a|`--input` +a|Specify a location of the __.yaml file to generate the deployment manifest. + +a|`--non-k8s-only` +a|Generate only non-Kubernetes templates, such as a Dockerfile. + +a|`--output-dir` +a|Specify a location to which the deployment manifests are saved. + +a|`--set` +a|Override values of attributes in the discovery manifest with the key-value pair entered from the CLI. +|=== diff --git a/docs/topics/mta-cli/ref_effort-level-estimation.adoc b/docs/topics/mta-cli/ref_effort-level-estimation.adoc new file mode 100644 index 00000000..d6861288 --- /dev/null +++ b/docs/topics/mta-cli/ref_effort-level-estimation.adoc @@ -0,0 +1,43 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc +// * docs/maven-guide/master.adoc +// * docs/rules-development-guide/master.adoc + +:_content-type: REFERENCE +[id="effort-level-estimation_{context}"] += Guidelines for the level of effort estimation + +The following are the general guidelines {ProductShortName} uses when estimating the level of effort required for a rule. + +.Guidelines for the level of effort estimation +[cols="25%,15%,60%", options="header"] +|==== +|Level of Effort +|Story Points +|Description + +|Information +|0 +|An informational warning with very low or no priority for migration. + +|Trivial +|1 +|The migration is a trivial change or a simple library swap with no or minimal API changes. + +|Complex +|3 +|The changes required for the migration task are complex, but have a documented solution. + +|Redesign +|5 +|The migration task requires a redesign or a complete library change, with significant API changes. + +|Rearchitecture +|7 +|The migration requires a complete rearchitecture of the component or subsystem. + +|Unknown +|13 +|The migration solution is not known and may need a complete rewrite. +|==== \ No newline at end of file diff --git a/docs/topics/mta-cli/ref_migration-tasks-categories.adoc b/docs/topics/mta-cli/ref_migration-tasks-categories.adoc new file mode 100644 index 00000000..52d8ad2d --- /dev/null +++ b/docs/topics/mta-cli/ref_migration-tasks-categories.adoc @@ -0,0 +1,24 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 + +:_mod-docs-content-type: REFERENCE + +[id="migration-tasks-categories_{context}"] += Migration tasks categories + +In addition to the xref:effort-level-estimation_rule-story-points[level of effort], you can categorize migration tasks to indicate the severity of the task. The following categories are used to group issues to help prioritize the migration effort. + +Mandatory:: The task must be completed for a successful migration. If the changes are not made, the resulting application will not build or run successfully. Examples include replacement of proprietary APIs that are not supported in the target platform. + +Optional:: If the migration task is not completed, the application should work, but the results might not be optimal. If the change is not made at the time of migration, it is recommended to put it on the schedule soon after your migration is completed. +//An example of this would be the upgrade of EJB 2.x code to EJB 3. + +Potential:: The task should be examined during the migration process, but there is not enough detailed information to determine if the task is mandatory for the migration to succeed. An example of this would be migrating a third-party proprietary type where there is no directly compatible type. + +Information:: The task is included to inform you of the existence of certain files. These might need to be examined or modified as part of the modernization effort, but changes are typically not required. +//An example of this would be the presence of a logging dependency or a Maven `pom.xml`. + +[role="_additional-resources"] +.Additional resources + +* link:{ProductDocRulesGuideURL}/rule_categories_rules-development-guide#rule_categories_rules-development-guide[Using custom rule categories] diff --git a/docs/topics/mta-cli/ref_mta-cli-analyze-flags.adoc b/docs/topics/mta-cli/ref_mta-cli-analyze-flags.adoc new file mode 100644 index 00000000..7f660212 --- /dev/null +++ b/docs/topics/mta-cli/ref_mta-cli-analyze-flags.adoc @@ -0,0 +1,61 @@ +:_newdoc-version: 2.18.3 +:_template-generated: 2025-04-09 + +:_mod-docs-content-type: REFERENCE + +[id="mta-cli-analyze-flags_{context}"] += The analyze command options + +The following are the options that you can use together with the `mta-cli analyze` command to adjust the command behavior to your needs. + +.`mta-cli analyze` command options +[options="header"] +|==== +|Option|Description +|`--analyze-known-libraries` (bool)|Analyze open-source libraries. +|`--context-lines` (int)|A number of lines of source code to include in the output for each incident. The default is 100. +|`--dependency-folders` (stringArray)|A directory for dependencies. +|`--enable-default-rulesets` (bool)|Run default rulesets with analysis. The default is `true`. +|`--help`|Display the available flags for the `analyze` command. +|`--http-proxy` (string)|An HTTP proxy string URL. +|`--https-proxy` (string)|An HTTPS proxy string URL. +|`--incident-selector` (string) a|An expression to select incidents based on custom variables, for example: + +---- +!package=io.demo.config-utils +---- +|`--input` (string)|A path to the application source code or a binary. +|`--jaeger-endpoint` (string)|A Jaeger endpoint to collect traces. +|`--json-output` (string)|Create analysis and dependence output as a JSON file. +|`--label-selector` (string)|Run rules based on specified label selector expression. +| `--list-languages` |List all languages in the source application. This flag is not supported for binary applications. +| `--list-providers` |List available supported providers. +|`--list-sources`|List rules for available migration sources. +|`--list-targets`|List rules for available migration targets. +|`--maven-settings` (string)|A path to the custom Maven settings file to use. +|`--mode` (string) a|An analysis mode. Must be set to either of the following values: + +* `full` (default) +* `source-only` +|`--no-proxy` (string)|Proxy-excluded URLs (relevant only with proxy). +|`--output` (string)|A path to the directory for analysis output. +|`--overwrite` (bool)|Overwrite the output directory. +|`--rules` (stringArray)|A filename or directory that contains rule files. +|`--skip-static-report` (bool)|Do not generate the static report. +|`--source` (string) a|A source technology to consider for the analysis. +To specify multiple sources, repeat the parameter, for example: + +---- +--source --source ... +---- +|`--target` (string) a|A target technology to consider for the analysis. +To specify multiple targets, repeat the parameter, for example: + +---- +--target --target ... +---- +|`--log-level uint32`|A log level. The default is 4. +|`--no-cleanup` (bool)|Do not clean up temporary resources. +|==== + + diff --git a/docs/topics/tech-tags.adoc b/docs/topics/mta-cli/ref_mta-tech-tags.adoc similarity index 99% rename from docs/topics/tech-tags.adoc rename to docs/topics/mta-cli/ref_mta-tech-tags.adoc index f6908117..b951f2df 100644 --- a/docs/topics/tech-tags.adoc +++ b/docs/topics/mta-cli/ref_mta-tech-tags.adoc @@ -3,7 +3,7 @@ // * docs/cli-guide/master.adoc :_content-type: REFERENCE -[id="tech-tags_{context}"] +[id="mta-tech-tags_{context}"] = Supported technology tags The following technology tags are supported in {ProductShortName} {ProductVersion}: diff --git a/docs/topics/mta-cli/ref_openrewrite-command-options.adoc b/docs/topics/mta-cli/ref_openrewrite-command-options.adoc new file mode 100644 index 00000000..d0ce6f8e --- /dev/null +++ b/docs/topics/mta-cli/ref_openrewrite-command-options.adoc @@ -0,0 +1,23 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-06-18 +:_mod-docs-content-type: REFERENCE + +[id="openrewrite-command-options_{context}"] += The openrewrite command options + +The following are the options that you can use together with the `mta-cli transform openrewrite` command to adjust the command behavior to your needs. + +.The mta-cli transform openrewrite command options +[options="header"] +|==== +|Option|Description +|`--goal` (string)|A target goal. The default is `"dryRun"`. +|`--help`|Display all `mta-cli transform openrewrite` command options. +|`--input` (string)|A path to the application source code directory. +|`--list-targets`|List all available OpenRewrite recipes. +|`-maven-settings` (string)|A path to a custom Maven settings file. +|`--target` (string)|A target OpenRewrite recipe. +|`--log-level uint32`|A log level. The default is `4`. +|`--no-cleanup`|Do not clean up temporary resources. +|==== + diff --git a/docs/topics/mta-cli/ref_rules-command-options.adoc b/docs/topics/mta-cli/ref_rules-command-options.adoc new file mode 100644 index 00000000..d6045cf5 --- /dev/null +++ b/docs/topics/mta-cli/ref_rules-command-options.adoc @@ -0,0 +1,20 @@ +:_newdoc-version: 2.18.5 +:_template-generated: 2025-06-18 +:_mod-docs-content-type: REFERENCE + +[id="rules-command-options_{context}"] += The rules command options + +The following are the options that you can use together with the `mta-cli transform rules` command to adjust the command behavior to your needs. + +.The the mta-cli transform rules command options +[options="header"] +|==== +|Option|Description +|`--help`|Display all `mta-cli transform rules` command options. +|`--input` (stringArray)|A path to XML rule files or a directory. +|`--output` (string)|A path to the output directory. +|`--log-level` (int)|A log level. The default is `5`. +|==== + + diff --git a/docs/topics/migration-paths.adoc b/docs/topics/mta-cli/ref_supported-migration-paths.adoc similarity index 61% rename from docs/topics/migration-paths.adoc rename to docs/topics/mta-cli/ref_supported-migration-paths.adoc index 4737b885..a853be4f 100644 --- a/docs/topics/migration-paths.adoc +++ b/docs/topics/mta-cli/ref_supported-migration-paths.adoc @@ -1,21 +1,14 @@ -// Module included in the following assemblies: -// -// * docs/getting-started-guide/master.adoc +:_newdoc-version: 2.18.3 +:_template-generated: 2025-05-28 -:_content-type: CONCEPT -[id="migration-paths_{context}"] -= Supported {ProductName} migration paths +:_mod-docs-content-type: REFERENCE -The {ProductName} ({ProductShortName}) supports the following migrations: +[id="supported-migration-paths_{context}"] += Supported {ProductShortName} migration paths -* Migrating from third-party enterprise application servers, such as Oracle WebLogic Server, to JBoss Enterprise Application Platform (JBoss EAP). -* Upgrading to the latest release of JBoss EAP. +You can run the {ProductFullName} analysis to assess your applications' suitability for migration to multiple target platforms. {ProductShortName} supports the following migration paths: -* Migrating from a Windows-only .NET 4.5+ Framework to cross-platform .NET 8.0. (Developer Preview) - -{ProductShortName} provides a comprehensive set of rules to assess the suitability of your applications for containerization and deployment on Red Hat OpenShift Container Platform (RHOCP). You can run an {ProductShortName} analysis to assess your applications' suitability for migration to multiple target platforms. - -.Supported Java migration paths: Source platform ⇒ Target platform +.Supported Java migration paths [width="99%",cols="19%,10%,10%,10%,10%,10%,10%,10%,10%",options="^,header"] |=== @@ -150,7 +143,9 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |=== -. .NET migration paths: Source platform ⇒ Target platform (Developer Preview) + + +..NET migration paths [options="^,header"] |=== @@ -162,3 +157,11 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |{icon-check} |=== + +:FeatureName: Analyzing applications written in the .NET language +include::../snippets/developer-preview-admonition.adoc[] + + +[role="_additional-resources"] +.Additional resources +* link:https://developers.redhat.com/products/mta/use-cases[Use cases and migration paths for {ProductName}] diff --git a/docs/topics/mta-optimize-performance.adoc b/docs/topics/mta-optimize-performance.adoc deleted file mode 100644 index 09289086..00000000 --- a/docs/topics/mta-optimize-performance.adoc +++ /dev/null @@ -1,28 +0,0 @@ -// Module included in the following assemblies: -// -// * docs/cli-guide/master.adoc - -:_content-type: CONCEPT -[id="optimize-performance_{context}"] -= Optimizing {ProductShortName} performance - -{ProductShortName} performance depends on a number of factors, including hardware configuration, the number and types of files in the application, the size and number of applications to be evaluated, and whether the application contains source or compiled code. For example, a file that is larger than 10 MB may need a lot of time to process. - -In general, {ProductShortName} spends about 40% of the time decompiling classes, 40% of the time executing rules, and the remainder of the time processing other tasks and generating reports. This section describes what you can do to improve the performance of {ProductShortName}. - -== Deploying and running the application - -Try these suggestions first before upgrading hardware. - -* If possible, run {ProductShortName} against the source code instead of the archives. This eliminates the need to decompile additional JARs and archives. -* Increase your ulimit when analyzing large applications. See link:https://access.redhat.com/solutions/60746[this Red Hat Knowledgebase article] for instructions on how to do this for Red Hat Enterprise Linux. -* If you have access to a server that has better resources than your laptop or desktop machine, you may want to consider running {ProductShortName} on that server. - -== Upgrading hardware - -If the application and command-line suggestions above do not improve performance, you may need to upgrade your hardware. - -* If you have access to a server that has better resources than your laptop/desktop, then you may want to consider running {ProductShortName} on that server. -* Very large applications that require decompilation have large memory requirements. 8 GB RAM is recommended. This allows 3 - 4 GB RAM for use by the JVM. -* An upgrade from a single or dual-core to a quad-core CPU processor provides better performance. -* Disk space and fragmentation can impact performance. A fast disk, especially a solid-state drive (SSD), with greater than 4 GB of defragmented disk space should improve performance. diff --git a/docs/topics/proc_running-the-containerless-mta-cli.adoc b/docs/topics/proc_running-the-containerless-mta-cli.adoc deleted file mode 100644 index 2187d5e0..00000000 --- a/docs/topics/proc_running-the-containerless-mta-cli.adoc +++ /dev/null @@ -1,95 +0,0 @@ -:_newdoc-version: 2.18.3 -:_template-generated: 2024-11-15 -:_mod-docs-content-type: PROCEDURE - -[id="running-the-containerless-mta-cli_{context}"] -= Running the containerless CLI - -Starting from {ProductShortName} 7.2.0, you can perform an application analysis for Java applications by using the {ProductShortName} CLI that does not require installation of a container runtime. - -[IMPORTANT] -==== -In {ProductShortName} 7.2.0 and later, containerless CLI is a default mode. To enable container runtime usage, you must set the `--run-local` flag to `false`: - ----- ---run-local=false ----- -==== - -.Prerequisites - -* You have OpenJDK version 17 or later installed on your system. -* You have Maven version 3.9.9 or later installed on your system. -* The CLI assumes that a path to the `mvn` binary is correctly registered in the system variable. Therefore, ensure that you added `mvn` to the following variable: -** `Path` for Windows. -** `PATH` for Linux and macOS. -* You have the `JAVA_HOME` environmental variable set. -* You have the `JVM_MAX_MEM` system variable set. -+ -[NOTE] -==== -If you do not set `JVM_MAX_MEM`, the analysis might hang. -==== - -.Procedure for Linux - -After unpacking the whole zip file to `~/.kantra`, add that path to the `$PATH` variable. - -[NOTE] -==== -Moving the `mta-cli` binary to `/usr/bin` requires root privileges, whereas adding that path to `$PATH` variable does not require root privileges. -==== - -. To extract the dependency zip file to `~/.kantra`, run: -+ -[source,terminal,subs="attributes+"] ----- -unzip $HOME/mta-cli...zip -d $HOME/.kantra ----- -. Add as a system-wide binary or add to the global `$PATH` variable: -.. For example, to add the `mta-cli` binary to `/usr/bin` as a system-wide binary, using `sudo`, run: -+ -[source,terminal,subs="attributes+"] ----- -sudo mv ~/.kantra/mta-cli /usr/bin/ ----- - -.. For example, to add to the global `$PATH` variable, run: -+ -[source,terminal,subs="attributes+"] ----- -export PATH=$HOME/.kantra:$PATH ----- - -+ -[NOTE] -==== -The CLI can run with the requirements moved to the directory from which you run an analysis. During the analysis, the CLI checks for the requirements in this directory first, and if it does not find the requirements, it searches for them in the `$HOME/.kantra` directory. -==== - -. Optional: Display all `mta-cli analyze` command options: -+ -[source,terminal,subs="attributes+"] ----- -mta-cli analyze --help ----- - -. Run the application analysis: -+ -[source,terminal,subs="attributes+"] ----- -$ mta-cli analyze --overwrite --input --output --target ----- -+ -The command arguments represent the following: - -** `--overwrite`: Overwrites the output folder if it exists. -** `--input`: The application to be analyzed. -** `--output`: The output directory for the generated reports. -** `--target`: The target technology for the application migration, for example, `eap8`. - - -[role="_additional-resources"] -.Additional resources - -* xref:installing-downloadable-cli-zip_cli-guide[Installing the CLI .zip file] diff --git a/docs/topics/templates/revision-info.adoc b/docs/topics/templates/revision-info.adoc deleted file mode 100644 index c92b2766..00000000 --- a/docs/topics/templates/revision-info.adoc +++ /dev/null @@ -1,8 +0,0 @@ -// ****************************************** -// * Revision information template. * -// * Add this to the end of every document. * -// ****************************************** - -{empty} + - -[right]_Revised on {localdate} {localtime}_