Collecting on WebSphere Liberty or Open Liberty

Edit online

This document uses Liberty to refer to both WebSphere Liberty and Open Liberty.

The Discovery tool is designed to analyze the WebSphere Application Server traditional and similar runtimes. However, it also provides tools to assist in modernizing from Liberty (typically on a VM) to Liberty in Containers. To do this we will use the binary scanner that is included with the Discovery tool, or the binary scanner can be downloaded separately. The results can be reviewed locally and will not be uploaded into Transformation Advisor.

Prerequisites

  • A copy of the application war or ear file(s) that are to be modernized to Liberty in Containers
  • A copy of the Liberty Migration Bundle

Downloading the scanning tool

If you have Transformation Advisor installed you can download the discovery tool and extract the binary scanner, otherwise you should download the binary scanner directly.

Downloading and installing the discovery tool (assumes you have Transformation Advisor installed)

To get started, complete the following steps from the Transformation Advisor UI:

  1. Create a workspace.

  2. On the new workspace page, click the Open discovery tool button and follow the instructions to download.

  3. Copy the downloaded file to your system in a directory where it has read-write-execute access.

  4. Decompress the downloaded file by issuing the command for your operating system:

    Linux: tar xvfz DiscoveryTool-Linux_<WORKSPACE_NAME>.tgz 

AIX: gunzip -c DiscoveryTool-AIX_<WORKSPACE_NAME>.tgz | tar xf -  

Solaris: tar xvfz DiscoveryTool-Solaris_<WORKSPACE_NAME>.tgz

z/OS: gunzip -c DiscoveryTool-zOS_<WORKSPACE_NAME>.tgz | tar xf -

Windows: unzip DiscoveryTool-Windows_<WORKSPACE_NAME>.zip

  5. Go to the discovery tool lib directory:

    cd transformationadvisor*/lib

  6. Copy the binary scanner jar file to the directory containing your application binaries.

    cp ta.binaryAppScanner* binaryAppScanner.jar

Downloading and installing the binary scanner

To get started, complete the following steps:

  1. Go to the Migration Toolkit for Application Binaries download page: https://www.ibm.com/support/pages/migration-toolkit-application-binaries
  2. Download the Migration Toolkit for Application Binaries.
  3. Run the following command: 
    java -jar binaryAppScannerInstaller.jar

  4. Accept the License and use the default values for product location when prompted.

  5. Copy the binary scanner to your application location

    cp /path/to/binaryAppScanner.jar .

Running the binary scanner to modernize to Liberty in Containers

You will execute the binary scanner against your application binaries, review the results and combine your existing server.xml file with the Liberty Migration Bundle to complete the modernization to Liberty in Containers.

The steps are as follows:

  1. Run the binary scanner analyze option against your application binary, replacing APP_NAME with your application name: 
    java -jar binaryAppScanner.jar <APP_NAME.war> --analyze --sourceAppServer=liberty --sourceJava=ibm8 --targetCloud=containers

  2. The analysis report will be generated:

    • APP_NAME.war_AnalysisReport.html: An HTML file that shows all potential modernization issues for the WebSphere Liberty runtime
    • OPTIONAL: You can generate additional reports with the following commands:
    java -jar binaryAppScanner.jar <APP_NAME.war> --inventory
    • Generate the inventory report
    java -jar binaryAppScanner.jar <APP_NAME.war> --evaluate
    • Generate the technology evaluation report
  3. Run the binary scanner generate configuration option against your application binary, replacing the APP_NAME with the name of your application: 
    java -jar binaryAppScanner.jar <APP_NAME.war> --generateConfig

  4. The server.xml file will be generated:

    • APP_NAME.war_server.xml: A server.xml file that includes the list of features required for the application.

  5. Review the analysis file (APP_NAME.war_AnalysisReport.html). We expect the issues to be informational and that no code changes will be needed before running on Liberty in Containers. If there are issues that are not informational (for example, when changing Java version), some code changes may be necessary.

  6. Download the Liberty Migration Bundle.

  7. Update the Liberty Migration Bundle for your chosen runtime and application:

    1. Unzip the Liberty Migration Bundle.
    2. Delete the Dockerfile for the runtime you are not modernizing to.
    3. Rename the Dockerfile for the chosen runtime from Dockerfile.runtime to Dockerfile.
    4. Delete the application-cr.yaml file for the runtime you are not modernizing to (found in the deploy directory).
    5. Rename the chosen runtime file from application-cr.yaml.runtime to application-cr.yaml.
    6. Edit the application-cr.yaml file and replace APP_NAME with your application name.
    7. Rename the file target/APP_NAME.war.placeholder, replacing APP_NAME with your application name.
    8. Replace the provided server.xml file in src/main/liberty/config/server.xml with your existing one.
    9. Replace the feature list in that file with the list from your analysis (APP_NAME.war_server.xml).
    10. Follow the steps in the README.md to modernize to containers.
    11. Replace any remaining APP_NAME placeholders with your application name where applicable.

Frequently Asked Questions

Can I change Java versions while modernizing to Liberty in Containers?

Yes. By default, source and target Java levels are Java 8. For example, to move from Java 8 to Java 17:

java -jar binaryAppScanner.jar <APP_NAME.war> --analyze --sourceAppServer=liberty --sourceJava=ibm8 --targetJava=java17 --targetCloud=containers

Always set your source Java correctly. If your existing application uses Java 17:

java -jar binaryAppScanner.jar <APP_NAME.war> --analyze --sourceAppServer=liberty --sourceJava=java17 --targetCloud=containers

Other options are available; run the command with --help to view them.

Can I skip the analysis and just use the migration bundle?

Yes, but the analysis is useful if you have limited experience with containers. It highlights common container-specific issues that may cause unexpected behavior (for example, data loss after container restart if files are not mounted on external volumes).

What dependencies does my application have?

This approach does not identify dependencies automatically. You must manually add any JARs the application would normally obtain from shared libraries or classpaths. The generic LibertyMigrationBundle does not include placeholder files for such dependencies.

My existing server.xml file has configuration for multiple applications. How do I find configuration specific to one application?

The features required for this application appear in the server.xml file from your analysis. Some configuration in the original file may not be needed; extra configuration does not prevent the application from running.

Can I upload the results to Transformation Advisor?

No. Uploading is not currently supported, but this capability may be added to Transformation Advisor in the future.