diff --git a/.gitignore b/.gitignore index 727eef49f7..69a8c089a0 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,9 @@ html/ */build/* Gemfile.lock */master.html -.idea/ \ No newline at end of file +.idea/ +.gitignore +.DS_Store +assets/.DS_Store +docs/.DS_Store +docs/topics/.DS_Store \ No newline at end of file diff --git a/docs/cli-guide/master.adoc b/docs/cli-guide/master.adoc index 57ef608e28..6546fc8ec5 100644 --- a/docs/cli-guide/master.adoc +++ b/docs/cli-guide/master.adoc @@ -16,35 +16,32 @@ include::topics/making-open-source-more-inclusive.adoc[] == Introduction -// About the {UserCLIBookName} -include::topics/about-cli-guide.adoc[leveloffset=+2] - // About {ProductName} include::topics/mta-what-is-the-toolkit.adoc[leveloffset=+2] +// About the {CLINameTitle} +include::topics/about-cli.adoc[leveloffset=+2] + +// About the {UserCLIBookName} +include::topics/about-cli-guide.adoc[leveloffset=+2] + +// Supported migration paths include::topics/migration-paths.adoc[leveloffset=+3] 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] - -// CLI known issues -include::topics/cli-tool-known-issues.adoc[leveloffset=+3] +include::topics/installing-cli-tool.adoc[leveloffset=+1] // Run the CLI -include::topics/mta-cli-run.adoc[leveloffset=+2] +include::topics/mta-cli-run.adoc[leveloffset=+1] // Analyze application source code -include::topics/mta-cli-analyze.adoc[leveloffset=+3] +include::topics/mta-cli-analyze.adoc[leveloffset=+2] // Transform XML rules to YAML -include::topics/mta-cli-transform.adoc[leveloffset=+3] +include::topics/mta-cli-transform.adoc[leveloffset=+2] // Use OpenRewrite recipes // include::topics/mta-using-openrewrite-recipes.adoc[leveloffset=+3] @@ -52,11 +49,11 @@ include::topics/mta-cli-transform.adoc[leveloffset=+3] // Available OpenRewrite recipes include::topics/available-openrewrite-recipes.adoc[leveloffset=+4] -// Access the Report -include::topics/access-report.adoc[leveloffset=+2] +// Reports +include::topics/access-report.adoc[leveloffset=+1] // Review the Reports -include::topics/mta-review-reports.adoc[leveloffset=+1] +include::topics/mta-review-reports.adoc[leveloffset=+2] // Export the Report in CSV Format // include::topics/csv-export.adoc[leveloffset=+1] diff --git a/docs/topics/about-cli-guide.adoc b/docs/topics/about-cli-guide.adoc index b88bec028a..74d34b592f 100644 --- a/docs/topics/about-cli-guide.adoc +++ b/docs/topics/about-cli-guide.adoc @@ -6,4 +6,4 @@ [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 or other components. It describes how to install and run the {CLIName}, review the generated reports, and take advantage of additional features. +This guide is for programmers, engineers, consultants, and others who want to use the {ProductName} ({ProductShortName}) to migrate Java and Go applications, or other software components. It describes how to install and run the {CLIName}, review the generated reports, and take advantage of additional features. diff --git a/docs/topics/about-cli.adoc b/docs/topics/about-cli.adoc index f51ef8adb2..e2c14fc375 100644 --- a/docs/topics/about-cli.adoc +++ b/docs/topics/about-cli.adoc @@ -7,7 +7,7 @@ [id="about-cli_{context}"] = The {ProductShortName} {CLINameTitle} -The {CLIName} is a command-line tool in the {ProductName} that you can use to assess and prioritize migration and modernization efforts for applications. It provides numerous reports that highlight the analysis without using the other tools. The {CLIName} includes a wide array of customization options. By using the {CLIName}, you can tune {ProductShortName} analysis options or integrate with external automation tools. +The {ProductName} {CLIName} is a command-line tool that you can use for assessing and managing your migration and modernization efforts for applications. It produces many reports that highlight the analysis without having to use the other tools. The {CLIName} includes a wide array of customization options, enabling you to tune the {ProductShortName} analysis options or integrate with external automation tools. ifndef::cli-guide[] For more information about using the {CLIName}, see link:{ProductDocUserGuideURL}[_{UserCLIBookName}_]. diff --git a/docs/topics/access-report.adoc b/docs/topics/access-report.adoc index 1b223b9572..192f44cb59 100644 --- a/docs/topics/access-report.adoc +++ b/docs/topics/access-report.adoc @@ -4,11 +4,11 @@ :_content-type: PROCEDURE [id="access-report_{context}"] -= Accessing reports += Reports -When you run the {ProductName}, a report is generated in the `` that you specify using the `--output` argument in the command line. +{ProductShortName} {CLIName} analyzes the application and generates a report of the analysis results. The report is saved to the `` that you specified in the `./ analyze` command, after the `--output` argument. -The output directory contains the following files and subdirectories: +Navigate to the directory and open the `-output` directory, which contains the following files and subdirectories: ---- / @@ -22,13 +22,13 @@ The output directory contains the following files and subdirectories: .Procedure -. Obtain the path of the `index.html` file of your report from the output that appears after you run {ProductShortName}: +. In the `-output` directory that you specified in the {ProductShortName} `./analyze` command, open the `index.html` file: + ---- Report created: /index.html Access it at this URL: file:////index.html ---- -. Open the `index.html` file by using a browser. +. The `index.html` file opens in a browser by default. + -The generated report is displayed. +The browser window shows the generated report. diff --git a/docs/topics/images/3-1-applications.png b/docs/topics/images/3-1-applications.png index 059dbaaf16..e6a9191872 100644 Binary files a/docs/topics/images/3-1-applications.png and b/docs/topics/images/3-1-applications.png differ diff --git a/docs/topics/images/3-2-a-dependencies.png b/docs/topics/images/3-2-a-dependencies.png new file mode 100644 index 0000000000..8541d86c67 Binary files /dev/null and b/docs/topics/images/3-2-a-dependencies.png differ diff --git a/docs/topics/images/3-3-dashboard.png b/docs/topics/images/3-3-dashboard.png index 97988b0c54..b6d27d8b8a 100644 Binary files a/docs/topics/images/3-3-dashboard.png and b/docs/topics/images/3-3-dashboard.png differ diff --git a/docs/topics/installing-cli-tool.adoc b/docs/topics/installing-cli-tool.adoc index 8b5b861bb6..47fbad763e 100644 --- a/docs/topics/installing-cli-tool.adoc +++ b/docs/topics/installing-cli-tool.adoc @@ -7,8 +7,7 @@ [id="installing-cli-tool_{context}"] = Installing the {CLINameTitle} -You can install the {CLINameTitle} on Linux, Windows, or macOS operating systems. - +You can install the {ProductShortName} {CLINameTitle} on Linux, Windows, or macOS operating systems. .Prerequisites @@ -24,6 +23,20 @@ Podman provides a command-line interface (CLI) familiar to anyone who has used t For more information on installing and using Podman, see link:https://podman.io/docs/installation[Podman installation instructions]. ==== +.Installation options + +You can run either of the following two options to install {ProductShortName} {CLINameTitle}: + +* Downloading the appropriate {ProductShortName} {CLINameTitle} `.zip` file, according to your operating system, and installing by using the command line. +* Running Podman on your computer and installing {ProductShortName} {CLIName} using Podman commands. + ++ +[WARNING] +==== +Although installation using Podman is possible, downloading and installing the {ProductShortName} {CLIName} `.zip` file is the preferred installation. +==== + + [id="installing-downloadable-cli-zip_{context}"] == Installing the {CLINameTitle} `.zip` file @@ -31,17 +44,31 @@ For more information on installing and using Podman, see link:https://podman.io/ To install using the downloadable `.zip` file: -. Navigate to the link:{DevDownloadPageURL}[{ProductShortName} Download page] and download the OS-specific CLI file or the `src` file: +. Navigate to the link:https://developers.redhat.com/products/mta/download[{ProductShortName} Download page] and download the OS-specific {ProductShortName} CLI file or the `mta-{ProductVersion}-cli-src` file: + ++ +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for Linux x86_64 +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for Linux aarch64 +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for macOS x86_64 +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for macOS aarch64 +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for Windows x86_64 +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for Windows aarch64 +* Migration Toolkit {CLINameTitle} - {CLINameTitle} for {ProductShortName} source Code + + -* {ProductShortNameLower}-{ProductVersion}-cli-linux.zip -* {ProductShortNameLower}-{ProductVersion}-cli-macos.zip -* {ProductShortNameLower}-{ProductVersion}-cli-windows.zip -* {ProductShortNameLower}-{ProductVersion}-cli-src.zip +[NOTE] +==== +Do not download and install the {ProductShortName} source code file if your computer runs one of the above operating systems. +==== . Extract the `.zip` file to a directory of your choice. The `.zip` file extracts a single binary, called *mta-cli*. + When you encounter `<{ProductShortName}_HOME>` in this guide, replace it with the actual path to your {ProductShortName} installation. +. Copy or save the `mta-cli` binary on Linux, `darwin-mta-cli` on macOS, or `mta-cli.exe` on Windows, to a known directory. ++ +Continue to xref:cli-run_cli-guide[Running the CLI] to run the CLI command. + [id="installing-using-podman_{context}"] == Installing the {CLINameTitle} using Podman @@ -60,10 +87,19 @@ To install using `podman pull`: [source,terminal] ---- podman login registry.redhat.io +---- + +. Enter your `Username` and `Password`. ++ +[source,terminal] +---- Username: Password: <***********> ---- -. Issue: ++ +If your `Username` and `Password` are correct, the terminal line should show `Login Succeeded!`. + +. Copy the binary `PATH` for system-wide use. + [source,terminal] ---- diff --git a/docs/topics/migration-paths.adoc b/docs/topics/migration-paths.adoc index b6d0950af4..9079f4761d 100644 --- a/docs/topics/migration-paths.adoc +++ b/docs/topics/migration-paths.adoc @@ -14,7 +14,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: {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 migration paths: Source platform ⇒ Target platform -[width="99%",cols="19%,10%,10%,10%,10%,10%,10%,10%,10%",options="^,header"] +[width="99%",cols="18%,9%,9%,9%,9%,9%,9%,9%,9%,9%",options="^,header"] |=== |Source platform{nbsp}⇒ @@ -26,6 +26,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |Spring Boot in Red Hat Runtimes |Quarkus |Open Liberty +|Azure App Service |Oracle WebLogic Server |{icon-check} @@ -36,6 +37,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |IBM WebSphere Application Server |{icon-check} @@ -46,10 +48,13 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |{icon-check} +|- |JBoss EAP 4 |{icon-x} footnoteref:[note2,Although {ProductShortName} does not currently provide rules for this migration path, Red Hat Consulting can assist with migration from any source platform to JBoss EAP 7.] -|{icon-check} |{icon-check} +|{icon-check} +|{icon-check} +|- |- |- |- @@ -65,6 +70,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |JBoss EAP 6 |{icon-check} @@ -75,6 +81,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |JBoss EAP 7 |{icon-check} @@ -85,6 +92,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |{icon-check} |- +|- |Thorntail |{icon-check} footnoteref:[note3,Requires JBoss Enterprise Application Platform expansion pack 2 (EAP XP 2)] @@ -95,6 +103,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |Oracle JDK |- @@ -105,6 +114,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |Camel 2 |- @@ -115,6 +125,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |Spring Boot |- @@ -125,6 +136,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |{icon-check} |{icon-check} |- +|- |Any Java application |- @@ -135,6 +147,7 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- |Any Java EE application |- @@ -145,4 +158,16 @@ The {ProductName} ({ProductShortName}) supports the following migrations: |- |- |- +|- + +|Azure +|- +|- +|- +|- +|- +|- +|- +|- +|{icon-check} |=== diff --git a/docs/topics/mta-cli-args.adoc b/docs/topics/mta-cli-args.adoc index 7b840c0f61..43451a0f33 100644 --- a/docs/topics/mta-cli-args.adoc +++ b/docs/topics/mta-cli-args.adoc @@ -207,7 +207,7 @@ A space-delimited list of the packages to be evaluated by {ProductShortName}. It ---- ---- -* In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third party packages. The `` argument is a package prefix; all subpackages will be scanned. For example, to scan the packages `com.mycustomapp` and `com.myotherapp`, use `--packages com.mycustomapp com.myotherapp` argument on the command line. -* While you can provide package names for standard Java EE third party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort. +* In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or third-party packages. The `` argument is a package prefix; all subpackages will be scanned. For example, to scan the packages `com.mycustomapp` and `com.myotherapp`, use `--packages com.mycustomapp com.myotherapp` argument on the command line. +* While you can provide package names for standard Java EE third-party software like `org.apache`, it is usually best not to include them as they should not impact the migration effort. //// diff --git a/docs/topics/mta-cli-run.adoc b/docs/topics/mta-cli-run.adoc index e72214444d..007bd14e8c 100644 --- a/docs/topics/mta-cli-run.adoc +++ b/docs/topics/mta-cli-run.adoc @@ -12,7 +12,7 @@ You can run {ProductShortName} against your application. . Open a terminal and navigate to the `<{ProductShortName}_HOME>/` directory. -. Execute the `{mta-cli}` script, or `{mta-cli}.exe` for Windows, and specify the appropriate arguments: +. Run the `{mta-cli}` script, or `{mta-cli}.exe` for Windows, or `darwin-{mta-cli}` for macOS, and specify the appropriate arguments: + [source,terminal,subs="attributes+"] diff --git a/docs/topics/mta-review-reports.adoc b/docs/topics/mta-review-reports.adoc index 5db1889498..5f479378bf 100644 --- a/docs/topics/mta-review-reports.adoc +++ b/docs/topics/mta-review-reports.adoc @@ -17,12 +17,12 @@ $ <{ProductShortName}_HOME>/bin/{mta-cli} --input /home/username/{mta-cli}-sourc ---- endif::cli-guide[] -Use a browser to open the `index.html` file located in the report output directory. This opens a landing page that lists the applications that were processed. Each row contains a high-level overview of the story points, number of incidents, and technologies encountered in that application. +Use a browser to open the `index.html` file located in the report output directory. This opens a landing page that lists the applications that were processed. Each row contains a high-level overview of the story points, number of incidents, and technologies encountered in that application. .Application list image::3-1-applications.png[Application list] -NOTE: The incidents and estimated story points change as new rules are added to {ProductShortName}. The values here may not match what you see when you test this application. +NOTE: The incidents and estimated story points change as new rules are added to {ProductShortName}. The values here might not match what you see when you test this application. The following table lists all of the reports and pages that can be accessed from this main {ProductShortName} landing page. Click the name of the application, *jee-example-app-1.0.0.ear*, to view the application report. @@ -46,11 +46,16 @@ The following table lists all of the reports and pages that can be accessed from Note that if an application shares archives with other analyzed applications, you will see a breakdown of how many story points are from shared archives and how many are unique to this application. -.Shared archives -image::3-2-shared-archives.png[Shared archives] +// .Shared archives +// image::3-2-shared-archives.png[Shared archives] Information about the archives that are shared among applications can be found in the Archives Shared by Multiple Applications reports. +If an application has dependencies, clicking the *Dependencies* tab to see a list of the application's dependencies. + +.Dependencies +image::3-2-a-dependencies.png[Dependencies] + [id="review-application-report_{context}"] == Application report @@ -66,6 +71,7 @@ The dashboard gives an overview of the entire application migration effort. It s .Dashboard image::3-3-dashboard.png[Dashboard] +// The image I have from the static HTML file does not show any Issues or Share archives. Is there a sample application that I can run that shows these? The top navigation bar lists the various reports that contain additional details about the migration of this application. Note that only those reports that are applicable to the current application will be available. @@ -78,7 +84,7 @@ The top navigation bar lists the various reports that contain additional details | Provides a concise summary of all issues that require attention. | Application details -| Provides a detailed overview of all resources found within the application that may need attention during the migration. +| Provides a detailed overview of all resources found within the application that might need attention during the migration. | Technologies | Displays all embedded libraries grouped by functionality, allowing you to quickly view the technologies used in each application. @@ -141,7 +147,7 @@ This report includes details about every issue that was raised by the selected m .Issues report image::3-4-issues-report.png[Issues report] -Each reported issue may be expanded, by clicking on the title, to obtain additional details. The following information is provided. +Each reported issue can be expanded, by clicking on the title, to obtain additional details. The following information is provided. * A list of files where the incidents occurred, along with the number of incidents within each file. If the file is a Java source file, then clicking the filename will direct you to the corresponding Source report. * A detailed description of the issue. This description outlines the problem, provides any known solutions, and references supporting documentation regarding either the issue or resolution. diff --git a/docs/topics/mta-what-is-the-toolkit.adoc b/docs/topics/mta-what-is-the-toolkit.adoc index 235aee1bda..321a676ceb 100644 --- a/docs/topics/mta-what-is-the-toolkit.adoc +++ b/docs/topics/mta-what-is-the-toolkit.adoc @@ -13,20 +13,28 @@ = About the {ProductName} [discrete] -== What is the {ProductName}? +== What is the {ProductName} -{ProductName} ({ProductShortName}) accelerates large-scale application modernization efforts across hybrid cloud environments on Red Hat OpenShift. This solution provides insight throughout the adoption process, at both the portfolio and application levels: inventory, assess, analyze, and manage applications for faster migration to OpenShift via the user interface. +{ProductName} ({ProductShortName}) accelerates large-scale application modernization efforts across hybrid cloud environments on {ocp-first}. This solution provides insight throughout the adoption process, at both the portfolio and application levels: inventory, assess, analyze, and manage applications for faster migration to OpenShift using the user interface or command line interface. -{ProductShortName} uses an extensive default questionnaire as the basis for assessing your applications, or you can create your own custom questionnaire, enabling you to estimate the difficulty, time, and other resources needed to prepare an application for containerization. You can use the results of an assessment as the basis for discussions between stakeholders to determine which applications are good candidates for containerization, which require significant work first, and which are not suitable for containerization. +{ProductShortName} uses an extensive default questionnaire as the basis for assessing your applications for difficulty, time, and other resources needed to prepare an application for containerization. You can also create your own custom questionnaires. -{ProductShortName} analyzes applications by applying one or more rulesets to each application considered to determine which specific lines of that application must be modified before it can be modernized. +The {ProductShortName} analysis reports assess the resources required to containerize an application. It separates the assessed applications according to 3 tiers: -{ProductShortName} examines application artifacts, including project source directories and application archives, and then produces an HTML report highlighting areas needing changes. +* Applications that are good candidates for containerization + +* Applications that require significant work before being modernized + +* Applications that are not suitable for containerization + +{ProductShortName} analyzes applications by applying one or more rulesets to each application considered. The rulesets find the specific lines of that application require modification before migrating or modernizing the application. + +{ProductShortName} examines application artifacts, including project source directories and application archives, and then produces an HTML report highlighting areas that need changes. [discrete] -== How does the {ProductName} simplify migration? +== How the {ProductName} simplifies migration -The {ProductName} looks for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application. +The {ProductName} analyzes the application by looking for common resources and known trouble spots when migrating applications. It provides a high-level view of the technologies used by the application. -{ProductShortName} generates a detailed report evaluating a migration or modernization path. This report can help you to estimate the effort required for large-scale projects and to reduce the work involved. +After analyzing the application, {ProductShortName} generates a detailed report evaluating a migration or modernization path. This report can help you estimate the effort required for large-scale projects and reduce the work involved.