Digital Developer Conference: Cloud Security 2021 -- Build the skills to secure your cloud and data Register free

Transform a traditional on-premises app and deploy it as a containerized app on Red Hat OpenShift

In this tutorial, we’ll use IBM Cloud Transformation Advisor, which is available standalone and as part of WebSphere Hybrid Edition, can help modernize IBM WebSphere, Red Hat JBoss, Oracle WebLogic, Apache Tomcat, IBM MQ, WebSphere Message Broker, and IBM Integration Bus applications. In this tutorial, we’ll use IBM Cloud Transformation Advisor to evaluate a traditional on-premises WebSphere Application Server application.

We’ll use Transformation Advisor to analyze the running application, download the generated migration bundle, and use its recommendations to deploy that app in a WebSphere Liberty container running on Red Hat OpenShift on IBM Cloud.

A sample web app is provided in our GitHub repo to demonstrate the migration from on-premises to IBM Cloud.



  1. Install IBM Cloud Transformation Advisor
  2. Launch Transformation Advisor
  3. Run the Data Collector
  4. Upload results
  5. View recommendations
  6. Create the migration bundle
  7. Test the application locally
  8. Deploy the application to OpenShift

1. Install IBM Cloud Transformation Advisor

Please refer to the deployment options to install Transformation Advisor.

This tutorial uses the Transformation Advisor that is installed on an OpenShift cluster via an operator. After installing the operator, you can create its service instance by following the instructions here.

2. Launch Transformation Advisor

Transformation Advisor is a tool that helps businesses modernize and migrate their applications from on-premises environments to the cloud. Refer to the Transformation Advisor Documentation to learn more about it.

To launch Transformation Advisor perform the following steps:

In the OpenShift Web Console, select Networking > Routes.


Click the location of the ui-route.

On the Welcome screen, click the Create new button to add a workspace.


Create a new workspace that will be used to contain your recommendations. The workspace name can be any string you want, such as the project name or the name for the portfolio of applications you will be analyzing.

Then, create a collection. This collection is an opportunity for you to subdivide your work even further into a more focused grouping. It would typically be associated with a single run of the data collector and may be the name of the individual WAS server that you will be running the data collector on.


Click Create. The data collector opens.


3. Run the data collector

The data collector, which is compatible with WebSphere Application Server 7.x or later, identifies which profiles are associated with the WebSphere installation along with the installed WebSphere and Java versions. It also identifies all WebSphere applications within each deployment manager and standalone profile. The tool generates one folder per profile and places analysis results within that directory.

Follow these steps to download and run the data collector in your WebSphere environment. If you do not want to run the data collector on your own WebSphere environment, you can use the sample files we saved in the data/examples folder of our GitHub repo and go to the next step: “Upload results” to continue.

3.1 Download the Data Collector

From your Transformation Advisor’s project you will see an option to download the Data Collector. Click the Download button. It will take you to a new page which has instructions to download, install, and run the data collector.

To download the data collector, select the appropriate source operating system and then click Download to start downloading the .tgz file.


3.2 Move and unzip the Data Collector

Important: The data collector is likely to consume a significant amount of resources while gathering data. Therefore, we recommend you run the tool in a pre-production environment. Depending on the number, size, and complexity of your applications the data collector might take quite some time to execute and upload results.

Once the data collector is downloaded locally, move the .tgz file from your local machine to your server where your WAS application is running. You can do this in many ways, but the following command is one method for moving the .tgz file:

sftp user@hostname <<< $'put transformationadvisor-Linux_appmod_coll1.tgz'

Ensure the file is in a directory where you have read, write, and execute access. Then, uncompress the file.

tar xvfz transformationadvisor-Linux_appmod_coll1.tgz

Finally, go to the data collector directory.

cd transformationadvisor*

3.3 Run the Data Collector

The command to run the data collector depends on the domain and also what do you want to analyze. Go to the section Run Tool, select a value for the domain and analysis of. It will generate the command for you to run the data collector.


To start the analysis of applications and its configuration on a specific WebSphere Application Server instance, run the following transformationadvisor command:

./bin/transformationadvisor -w /opt/IBM/WebSphere/AppServer -p AppSrv01

The data collector will take some time to run. During this process, you can keep track of its progress by checking your command line.

4. Upload results

If there is a connection between your WebSphere Application Server system and the Transformation Advisor, then the results will be uploaded automatically. If the results are uploaded automatically, you can proceed to the next step: “View recommendations”.

If there is no connection, then you need to provide the data collector output to the Transformation Advisor. The data collector will return a .zip file containing your application data. Use the Upload data option to upload the .zip files.

  1. Find the results for each profile. These are .zip files created by the data collector with the same name as the profile. You will find the .zip files in the transformationadvisor directory of the data collector.

  2. Copy the .zip files to your local system.

  3. Go to Transformation Advisor. Navigate to your collection and click Upload.

  4. Select the .zip files using the Drop or Add File link, and click the Upload button to upload the files.


5. View recommendations

Once the Data Collector has uploaded its results you will be able to view the analysis in the Transformation Advisor project’s console. Note that the cost estimates displayed by the tool are high-level estimates and may vary widely based on skills and other factors not considered by the tool.

TIP: You can use the Advanced Settings gear icon to change the Dev cost multiplier setting and adjust the estimates for your team.


The recommendations page shows you a table with a summary row for each application found on your application server. Each row contains the following information:

Column Description
A drop-down arrow lets you expand the summary row to see the analysis for other targets.
Alert icons may appear to indicate apps that are incompatible with a target.
Application The name of the EAR/WAR file found on the application server.
Complexity An indicator to show how complex Transformation Advisor considers this application to be if you were to migrate it to the cloud.
Tech match This is a percentage and if less than 100% it indicates that there may be some technologies that are not suitable for the recommended platform. You should investigate the details and ensure your application is actually using the technologies.
Dependencies This shows potential external dependencies detected during the scan. Work may be needed to configure access to these external dependencies.
Issues This indicates the number and severity of potential issues migrating the application.
Est. dev cost This is an estimate in days of the development effort to perform the migration.
The Migration plan button will take you to the Migration page for the application.

Each column in the table is sortable. There is also a Search items box that allows you to filter out rows of data. You can use the + symbol to see only rows that match all your terms (for example, Liberty+Simple). You can filter by complexity using the filter button.

Clicking on your application name will take you to more information about the discovered complexity and issue details. For starters, the complexity rating is explained for you.


You will also see details for each issue and dependency discovered:


There will be additional sections to show any technology issues, external dependencies, and additional information related to your application transformation.

Scroll to the end of the recommendations screen to find three links to further detailed reports.


The three reports are described as follows:

  • Analysis Report The binary scanner’s detailed migration report digs deeper to understand the nitty-gritty details of the migration. The detailed report helps with migration issues like deprecated or removed APIs, Java SE version differences, and Java EE behavior differences. Please note that the Transformation Advisor uses a rule system based on common occurring events seen in real applications to enhance the base reports and to provide practical guidance. As a result of this some items may show a different severity level in Transformation Advisor than they do in the detailed binary scanner reports.


  • Technology Report The binary scanner can examine your application and generate the Application Evaluation Report, which shows which editions of WebSphere Application Server are best suited to run the application. The report provides a list of Java EE programming models that are used by the application, and it indicates on which platforms the application can be supported.


  • Inventory Report The binary scanner has an inventory report that helps you examine what’s in your application including the number of modules and the technologies in those modules. It also gives you a view of all the utility JAR files in the application that tend to accumulate over time. Potential deployment problems and performance considerations are also included.


6. Create the migration bundle

In this step, we will use Transformation Advisor to generate a migration bundle that includes code to build and deploy our application. From the Transformation Advisor console, click the context menu for the application that you want to migrate, and choose the View migration plan option.


In the Migration plan screen, choose the following options:

  • Build type: Choose the Binary option
  • Application dependencies: Choose Manual upload
  • Uploaded files: Upload modresorts-1.0.war
  • Choose to Download the bundle locally.

migration bundle

Transformation Advisor will automatically create several artifacts that you need to get your application running in a Liberty container on an OpenShift cluster. This includes a Dockerfile, a Liberty server.xml configuration file, and other custom resources (CR).

Once the bundle is uncompressed, it should have the following structure:

├── Dockerfile
├── deploy
│   ├── application-cr.yaml
├── pom.xml
├── src
│   └── main
│       ├── liberty
│       │   ├── config
│       │   │   └── server.xml
│       │   └── lib
│       └── webapp
│           ├── WEB-INF
│           │   └── web.xml
│           └── index.html
├── target
│   ├── modresorts-1.0.war

Optionally, you can create a new repo to save this code. If you’re using GitHub, then run the below commands to push the source files up.

git add -A
git commit -m "Add source code files"
git push

For an example repo, check out

7. Test the application locally

Before pushing our application to OpenShift, we can build and run it locally. To build it, use docker build.

docker build -t migrated-mod-resorts:v1 .

And, to run it locally, use docker run.

docker run -p 9080:9080 migrated-mod-resorts:v1

Opening a browser to localhost:9080/resorts should show the application running.

Optionally, create a new repository on an image registry, like DockerHub, and run the command below to push your image.

docker build -t <YOUR_DOCKERHUB_USERNAME>/migrated-mod-resorts:v1 .
docker push <YOUR_DOCKERHUB_USERNAME>/migrated-mod-resorts:v1

For an example image, check out

8. Deploy the application to OpenShift

Finally, we can deploy the application to Red Hat OpenShift. This tutorial uses the OpenShift cluster managed by IBM Cloud.

8.1 Access the OpenShift Cluster

To find your OpenShift cluster go to the Kubernetes Cluster List or from the IBM Cloud console go to Clusters>Your OpenShift Cluster>OpenShift web console.


From the OpenShift web console, click the menu in the upper right corner (the label contains your email address), and select Copy Login Command. Click Display token and paste the command into a terminal session. For example:

oc login --token=xxxx --server=

Next, create a new project to run your application:

oc new-project migrated-mod-resorts

8.2 Deploy the new bundle

Run the oc new-app command to deploy an application. Applications can be deployed by referencing a git repository or image registry. The following command finds the containerized application on a public DockerHub account.

$ oc new-app stevemar/migrated-mod-resorts:v1
# oc new-app <YOUR_DOCKERHUB_USERNAME>/migrated-mod-resorts:v1
# oc new-app <YOUR_GITHUB_REPO>

Run the following commands to check the status of the deployment. When the oc status command returns a positive message, then run the oc expose command to make the application publicly visible.

$ oc status ## to check the status of the previous command and wait till it says "deployment #1 deployed..."

$ oc expose svc/migrated-mod-resorts  ## this command exposes service after creating app

# Verify the pods and services
$ oc get pods       ## it will show a pod running with modapp-openshift-** name
$ oc get services   ## it will show a service running with modapp-openshift name

8.3 Access the migrated app

To get the URL of the migrated application, run the oc get routes command.

oc get routes

Open a browser, copy and paste the URL, and add a /resorts to the end of the path to view the migrated application.


Summary and next steps

In this tutorial, we showed you how to use Transformation Advisor to analyze a running application, download the generated migration bundle, and use its recommendations to deploy that app in a WebSphere Liberty container running on Red Hat OpenShift on IBM Cloud.

To explore more of the strategies and tooling you can use to modernize your applications, check out the tutorials, articles, and more on the Application Modernization hub on IBM Developer.