title	recommendations	description	author	ms.author	ms.service	ms.topic	ms.date	keywords	ms.custom
Deploy a Java application with Open Liberty/WebSphere Liberty on an Azure Red Hat OpenShift 4 cluster	false	Deploy a Java application with Open Liberty/WebSphere Liberty on an Azure Red Hat OpenShift 4 cluster.	majguo	jiangma	azure-redhat-openshift	conceptual	10/30/2020	java, jakartaee, javaee, microprofile, open-liberty, websphere-liberty, aro, openshift, red hat	devx-track-java, devx-track-javaee, devx-track-javaee-liberty, devx-track-javaee-liberty-aro

Deploy a Java application with Open Liberty/WebSphere Liberty on an ARO cluster

This guide demonstrates how to run your Java, Java EE, Jakarta EE, or MicroProfile application on the Open Liberty/WebSphere Liberty runtime and then deploy the containerized application to an Azure Red Hat OpenShift (ARO) 4 cluster using the Open Liberty Operator. This article will walk you through preparing a Liberty application, building the application Docker image and running the containerized application on an ARO 4 cluster. For more information on Open Liberty, see the Open Liberty project page.For more information on WebSphere Liberty, see the WebSphere Liberty product page.

[!INCLUDE aro-support]

Prerequisites

[!INCLUDE aro-quota]

Complete the following prerequisites to successfully walk through this guide.

Prepare a local machine with Unix-like operating system installed (for example, Ubuntu, macOS).
Install a Java SE implementation (for example, AdoptOpenJDK OpenJDK 8 LTS/OpenJ9).
Install Maven 3.5.0 or higher.
Install Docker for your OS.
Install Azure CLI 2.0.75 or later.
Check and install envsubst if it's not pre-installed in your operating system.
Clone the code for this sample on your local system. The sample is on GitHub.
Follow the instructions in Create an Azure Red Hat OpenShift 4 cluster.

Though the "Get a Red Hat pull secret" step is labeled as optional, it is required for this article. The pull secret enables your Azure Red Hat OpenShift cluster to find the Open Liberty Operator.

If you plan to run memory-intensive applications on the cluster, specify the proper virtual machine size for the worker nodes using the --worker-vm-size parameter. For example, Standard_E4s_v3 is the minimum virtual machine size to install the Elasticsearch Operator on a cluster. For more information, see:
Connect to the cluster by following the steps in Connect to an Azure Red Hat OpenShift 4 cluster.
- Be sure to follow the steps in "Install the OpenShift CLI" because we'll use the oc command later in this article.
- Write down the cluster console URL. It will look like https://console-openshift-console.apps.<random>.<region>.aroapp.io/.
- Take note of the kubeadmin credentials.
- Be sure to follow the steps in "Connect using the OpenShift CLI" with the kubeadmin credentials.

Install the Open Liberty OpenShift Operator

After creating and connecting to the cluster, install the Open Liberty Operator. The main starting page for the Open Liberty Operator is on GitHub.

Sign in to the OpenShift web console from your browser using the kubeadmin credentials.
Navigate to Operators > OperatorHub and search for Open Liberty.
Select Open Liberty from the search results.
Select Install.
In the page Install Operator, check beta2 for Update channel, All namespaces on the cluster (default) for Installation mode, and Automatic for Update approval:
Select Install and wait a minute or two until the installation completes.
Observe the Open Liberty Operator is successfully installed and ready for use. If you don't, diagnose and resolve the problem before continuing.

:::image type="content" source="media/howto-deploy-java-liberty-app/open-liberty-operator-installed.png" alt-text="Installed Operators showing Open Liberty is installed.":::

Create an OpenShift namespace for the Java app

Follow the instructions below to create an OpenShift namespace for use with your app.

Make sure you have signed in to the OpenShift web console from your browser using the kubeadmin credentials.
Navigate to Administration > Namespaces > Create Namespace.
Fill in open-liberty-demo for Name and select Create, as shown next.

Create an Azure Database for MySQL

Follow the instructions below to set up an Azure Database for MySQL for use with your app. If your application doesn't require a database, you can skip this section.

Create a single database in Azure SQL Database by following the steps in: Quickstart: Create an Azure Database for MySQL server by using the Azure portal. Return to this document after creating the database.
[!NOTE]
- At the Basics step, write down the Server name.mysql.database.azure.com, Server admin login and Password.
Once your database is created, open your SQL server > Connection security and complete the following settings:
1. Set Allow access to Azure services to Yes.
2. Select Add current client IP address.
3. Set Minimal TLS Version to >1.0 and select Save.

Open your SQL database > Connection strings > Select JDBC. Write down the Port number following sql server address. For example, 3306 is the port number in the example below.

String url ="jdbc:mysql://<Server name>.mysql.database.azure.com:3306/{your_database}?useSSL=true&requireSSL=false"; myDbConn = DriverManager.getConnection(url, "<Server admin login>", {your_password});

If you didn't create a database in above steps, follow the steps in Quickstart: Create an Azure Database for MySQL server by using the Azure portal#connect-to-the-server-by-using-mysqlexe to create one. Return to this document after creating the database.
[!NOTE]
- Write down the Database name you created.

Prepare the Liberty application

We'll use a Java EE 8 application as our example in this guide. Open Liberty is a Java EE 8 full profile compatible server, so it can easily run the application. Open Liberty is also Jakarta EE 8 full profile compatible.

Run the application on Open Liberty

To run the application on Open Liberty, you need to create an Open Liberty server configuration file so that the Liberty Maven plugin can package the application for deployment. The Liberty Maven plugin is not required to deploy the application to OpenShift. However, we'll use it in this example with Open Liberty’s developer (dev) mode. Developer mode lets you easily run the application locally. Complete the following steps on your local computer.

with DB connection

Follow the steps in this section to prepare the sample application for later use in this article. These steps use Maven and the liberty-maven-plugin. To learn more about the liberty-maven-plugin, see Building a web application with Maven.

Check out the application

Clone the sample code for this guide. The sample is on GitHub. There are three samples in the repository. We will use open-liberty-on-aro/3-integration/connect-db/mysql. Here is the file structure of the application.

open-liberty-on-aro/3-integration/connect-db/mysql
├─ src/main/
│  ├─ aro/
│  │  ├─ db-secret.yaml
│  │  ├─ openlibertyapplication.yaml
│  ├─ docker/
│  │  ├─ Dockerfile
│  │  ├─ Dockerfile-local
│  │  ├─ Dockerfile-wlp
│  │  ├─ Dockerfile-wlp-local
│  ├─ liberty/config/
│  │  ├─ server.xml
│  ├─ java/
│  ├─ resources/
│  ├─ webapp/
├─ pom.xml

The directories java, resources, and webapp contain the source code of the sample application. The code declares and uses a data source named jdbc/JavaEECafeDB.

In the aro directory, we placed two deployment files. db-secret.xml is used to create Secrets with DB connection credentials. The file openlibertyapplication.yaml is used to deploy the application image.

In the docker directory, we placed four Dockerfiles. Dockerfile-local is used for local debugging, and Dockerfile is used to build the image for an ARO deployment. These two files work with Open Liberty. Dockerfile-wlp-local and Dockerfile-wlp are also used for local debugging and to build the image for an ARO deployment respectively, but instead work with WebSphere Liberty.

In the liberty/config directory, the server.xml is used to configure the DB connection for the Open Liberty and WebSphere Liberty cluster.

Build project

Now that you have gathered the necessary properties, you can build the application. The POM file for the project reads many properties from the environment.

cd <path-to-your-repo>/open-liberty-on-aro/3-integration/connect-db/mysql

# The following variables will be used for deployment file generation
export DB_SERVER_NAME=<Server name>.mysql.database.azure.com
export DB_PORT_NUMBER=3306
export DB_NAME=<Database name>
export DB_USER=<Server admin username>@<Server name>
export DB_PASSWORD=<Server admin password>
export NAMESPACE=open-liberty-demo

mvn clean install

Test your application locally

Use the liberty:devc command to run and test the project locally before dealing with any Azure complexity. For more information on liberty:devc, see the Liberty Plugin documentation. In the sample application, we've prepared Dockerfile-local and Dockerfile-wlp-local for use with liberty:devc.

Start your local docker environment if you haven't done so already. The instructions for doing this vary depending on the host operating system.

Start the application in liberty:devc mode

cd <path-to-your-repo>/open-liberty-on-aro/3-integration/connect-db/mysql

# If you are running with Open Liberty
mvn liberty:devc -Ddb.server.name=${DB_SERVER_NAME} -Ddb.port.number=${DB_PORT_NUMBER} -Ddb.name=${DB_NAME} -Ddb.user=${DB_USER} -Ddb.password=${DB_PASSWORD} -Ddockerfile=target/Dockerfile-local

# If you are running with WebSphere Liberty
mvn liberty:devc -Ddb.server.name=${DB_SERVER_NAME} -Ddb.port.number=${DB_PORT_NUMBER} -Ddb.name=${DB_NAME} -Ddb.user=${DB_USER} -Ddb.password=${DB_PASSWORD} -Ddockerfile=target/Dockerfile-wlp-local

Verify the application works as expected. You should see a message similar to [INFO] [AUDIT] CWWKZ0003I: The application javaee-cafe updated in 1.930 seconds. in the command output if successful. Go to http://localhost:9080/ in your browser and verify the application is accessible and all functions are working.
Press Ctrl+C to stop liberty:devc mode.

without DB connection

Copy 2-simple/src/main/liberty/config/server.xml to 1-start/src/main/liberty/config, overwriting the existing zero-length file. This server.xml configures the Open Liberty server with Java EE features.
Copy 2-simple/pom.xml to 1-start/pom.xml. This step adds the liberty-maven-plugin to the POM.
Change directory to 1-start of your local clone.
Run mvn clean package in a console to generate a war package javaee-cafe.war in the directory ./target.
Run mvn liberty:dev to start Open Liberty in dev mode.

Wait until the server starts. The console output should end with the following message:

[INFO] CWWKM2015I: Match number: 1 is [6/10/20 10:26:09:517 CST] 00000022 com.ibm.ws.kernel.feature.internal.FeatureManager            A CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 6.447 seconds..
[INFO] Press the Enter key to run tests on demand. To stop the server and quit dev mode, use Ctrl-C or type 'q' and press the Enter key.
[INFO] Source compilation was successful.

Open http://localhost:9080/ in your browser to visit the application home page. The application will look similar to the following image:
Press Control-C to stop the application and Open Liberty server.

The directory 2-simple of your local clone shows the Maven project with the above changes already applied.

Prepare the application image

To deploy and run your Liberty application on an ARO 4 cluster, containerize your application as a Docker image using Open Liberty container images or WebSphere Liberty container images.

Complete the following steps to build the application image:

with DB connection

Build the application and push to the image stream

Since you have already successfully run the app in the Liberty Docker container, you're going to build the image remotely on the cluster by executing the following commands.

Make sure you have already signed in to the OpenShift CLI using the kubeadmin credentials.

Identify the source directory and Dockerfile.

cd <path-to-your-repo>/open-liberty-on-aro/3-integration/connect-db/mysql

# Fetch maven artifactId as image name, maven build version as image version
IMAGE_NAME=$(mvn -q -Dexec.executable=echo -Dexec.args='${project.artifactId}' --non-recursive exec:exec)
IMAGE_VERSION=$(mvn -q -Dexec.executable=echo -Dexec.args='${project.version}' --non-recursive exec:exec)
cd <path-to-your-repo>/open-liberty-on-aro/3-integration/connect-db/mysql/target

# If you are building with Open Liberty base image, the existing Dockerfile is ready for you

# If you are building with WebSphere Liberty base image, uncomment and execute the following two commands to rename Dockerfile-wlp to Dockerfile
# mv Dockerfile Dockerfile.backup
# mv Dockerfile-wlp Dockerfile

Create an image stream.
```
oc create imagestream ${IMAGE_NAME}
```

Create a build configuration which specifies the image stream tag of the build output.

oc new-build --name ${IMAGE_NAME}-config --binary --strategy docker --to ${IMAGE_NAME}:${IMAGE_VERSION}

Start the build to upload local contents, containerize, and output to the image stream tag specified before.
```
oc start-build ${IMAGE_NAME}-config --from-dir . --follow
```

without DB connection

Build and run the application locally with Docker

Before deploying the containerized application to a remote cluster, build and run with your local Docker to verify whether it works:

Change directory to 2-simple of your local clone.
Run mvn clean package to package the application.

Run one of the following commands to build the application image.

Build with Open Liberty base image:

# Build and tag application image. This will cause Docker to pull the necessary Open Liberty base images.
docker build -t javaee-cafe-simple:1.0.0 --pull .

Build with WebSphere Liberty base image:

# Build and tag application image. This will cause Docker to pull the necessary WebSphere Liberty base images.
docker build -t javaee-cafe-simple:1.0.0 --pull --file=Dockerfile-wlp .

Run docker run -it --rm -p 9080:9080 javaee-cafe-simple:1.0.0 in your console.
Wait for Liberty server to start and the application to deploy successfully.
Open http://localhost:9080/ in your browser to visit the application home page.
Press Control-C to stop the application and Liberty server.

Build the application and push to the image stream

When you're satisfied with the state of the application, you're going to build the image remotely on the cluster by executing the following commands.

Make sure you have already signed in to the OpenShift CLI using the kubeadmin credentials.

Identity the source directory and the Dockerfile.

cd <path-to-your-repo>/open-liberty-on-aro/2-simple

# If you are building with Open Liberty base image, the existing Dockerfile is ready for you

# If you are building with WebSphere Liberty base image, uncomment and execute the following two commands to rename Dockerfile-wlp to Dockerfile
# mv Dockerfile Dockerfile.backup
# mv Dockerfile-wlp Dockerfile

Create an image stream.

oc create imagestream javaee-cafe-simple

Create a build configuration which specifies the image stream tag of the build output.

oc new-build --name javaee-cafe-simple-config --binary --strategy docker --to javaee-cafe-simple:1.0.0

Start the build to upload local contents, containerize, and output to the image stream tag specified before.
```
oc start-build javaee-cafe-simple-config --from-dir . --follow
```

Deploy application on the ARO 4 cluster

Now you can deploy the sample Liberty application to the Azure Red Hat OpenShift 4 cluster you created earlier when working through the prerequisites.

with DB from web console

Deploy the application from the web console

Because we use the Open Liberty Operator to manage Liberty applications, we need to create an instance of its Custom Resource Definition, of type "OpenLibertyApplication". The Operator will then take care of all aspects of managing the OpenShift resources required for deployment.

Sign in to the OpenShift web console from your browser using the kubeadmin credentials.
Expand Home, Select Projects > open-liberty-demo.
Navigate to Operators > Installed Operators.
In the middle of the page, select Open Liberty Operator.
In the middle of the page, select Open Liberty Application. The navigation of items in the user interface mirrors the actual containment hierarchy of technologies in use.
Select Create OpenLibertyApplication
Replace the generated yaml with yours, which is located at <path-to-repo>/3-integration/connect-db/mysql/target/openlibertyapplication.yaml.
Select Create. You'll be returned to the list of OpenLibertyApplications.
Navigate to Workloads > Secrets.
Select Create > From YAML.
Replace the generated yaml with yours, which is located at <path-to-repo>/3-integration/connect-db/mysql/target/db-secret.yaml.
Select Create. You'll be returned to the Secret details page.
Select Add Secret to workload, then select javaee-cafe-mysql from the dropdown box, then select Save.
Navigate to Operators > Installed Operators > Open Liberty Operator > Open Liberty Application.
Select javaee-cafe-mysql.
In the middle of the page, select Resources.
In the table, select the link for javaee-cafe-mysql with the Kind of Route.
On the page that opens, select the link below Location.

You'll see the application home page opened in the browser.

with DB from CLI

Deploy the application from CLI

Instead of using the web console GUI, you can deploy the application from the CLI. If you haven't already done so, download and install the oc command-line tool by following the steps in Red Hat documentation: Getting Started with the CLI.

Now you can deploy the sample Liberty application to the ARO 4 cluster with the following steps.

Make sure you have already signed in to the OpenShift CLI using the kubeadmin credentials.

Run the following commands to deploy the application.

# Change directory to "<path-to-repo>/3-integration/connect-db/mysql/target"
cd <path-to-repo>/3-integration/connect-db/mysql/target

# Change project to "open-liberty-demo"
oc project open-liberty-demo 

# Create DB secret
oc create -f db-secret.yaml

# Create the deployment
oc create -f openlibertyapplication.yaml

# Check if OpenLibertyApplication instance is created
oc get openlibertyapplication ${IMAGE_NAME}

# Check if deployment created by Operator is ready
oc get deployment ${IMAGE_NAME}

# Get host of the route
HOST=$(oc get route ${IMAGE_NAME} --template='{{ .spec.host }}')
echo "Route Host: $HOST"

Once the Liberty application is up and running, open the output of Route Host in your browser to visit the application home page.

without DB from web console

Deploy the application from the web console

Because we use the Open Liberty Operator to manage Liberty applications, we need to create an instance of its Custom Resource Definition, of type "OpenLibertyApplication". The Operator will then take care of all aspects of managing the OpenShift resources required for deployment.

Sign in to the OpenShift web console from your browser using the kubeadmin credentials.
Expand Home, Select Projects > open-liberty-demo.
Navigate to Operators > Installed Operators.
In the middle of the page, select Open Liberty Operator.
In the middle of the page, select Open Liberty Application. The navigation of items in the user interface mirrors the actual containment hierarchy of technologies in use.
Select Create OpenLibertyApplication
Replace the generated yaml with yours, which is located at <path-to-repo>/2-simple/openlibertyapplication.yaml.
Select Create. You'll be returned to the list of OpenLibertyApplications.
Select javaee-cafe-simple.
In the middle of the page, select Resources.
In the table, select the link for javaee-cafe-simple with the Kind of Route.
On the page that opens, select the link below Location.

You'll see the application home page opened in the browser.

Delete the application from the web console

When you're done with the application, follow these steps to delete the application from Open Shift.

In the left navigation pane, expand the entry for Operators.
Select Installed Operators.
Select Open Liberty Operator.
In the middle of the page select Open Liberty Application.
Select the vertical ellipsis (three vertical dots) then select Delete OpenLiberty Application.

without DB from CLI

Deploy the application from CLI

Instead of using the web console GUI, you can deploy the application from the CLI. If you haven't already done so, download and install the oc command-line tool by following Red Hat documentation Getting Started with the CLI.

Make sure you have already signed in to the OpenShift CLI using the kubeadmin credentials.

Change directory to 2-simple of your local clone, and run the following commands to deploy your Liberty application to the ARO 4 cluster. Command output is also shown inline.

# Switch to namespace "open-liberty-demo" where resources of demo app will belong to
oc project open-liberty-demo

Now using (or already on) project "open-liberty-demo" on server "https://api.aqlm62xm.rnfghf.aroapp.io:6443".

# Create OpenLibertyApplication "javaee-cafe-simple"
oc create -f openlibertyapplication.yaml

openlibertyapplication.openliberty.io/javaee-cafe-simple created

# Check if OpenLibertyApplication instance is created
oc get openlibertyapplication javaee-cafe-simple

NAME                 IMAGE                      EXPOSED   RECONCILED   AGE
javaee-cafe-simple   javaee-cafe-simple:1.0.0   true      True         36s

# Check if deployment created by Operator is ready
oc get deployment javaee-cafe-simple

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
javaee-cafe-simple   1/1     1            0           102s

Check to see 1/1 under the READY column before you continue. If not, investigate and resolve the problem before continuing.
Discover the host of route to the application with the oc get route command, as shown here.
```
# Get host of the route
HOST=$(oc get route javaee-cafe-simple --template='{{ .spec.host }}')
echo "Route Host: $HOST"

Route Host: javaee-cafe-simple-open-liberty-demo.apps.aqlm62xm.rnfghf.aroapp.io
```
Once the Liberty application is up and running, open the output of Route Host in your browser to visit the application home page.

Delete the application from CLI

Delete the application from the CLI by executing this command.

oc delete -f openlibertyapplication.yaml

Clean up resources

Delete the ARO cluster by following the steps in Tutorial: Delete an Azure Red Hat OpenShift 4 cluster

Next steps

In this guide, you learned how to:

[!div class="checklist"]

Prepare the Liberty application

Build the application image

Run the containerized application on an ARO 4 cluster using the GUI and the CLI

You can learn more from references used in this guide:

Open Liberty
Azure Red Hat OpenShift
Open Liberty Operator
Open Liberty Server Configuration
Liberty Maven Plugin
Open Liberty Container Images
WebSphere Liberty Container Images

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

howto-deploy-java-liberty-app.md

howto-deploy-java-liberty-app.md

Deploy a Java application with Open Liberty/WebSphere Liberty on an ARO cluster

Prerequisites

Install the Open Liberty OpenShift Operator

Create an OpenShift namespace for the Java app

Create an Azure Database for MySQL

Prepare the Liberty application

Run the application on Open Liberty

with DB connection

Check out the application

Build project

Test your application locally

without DB connection

Prepare the application image

with DB connection

Build the application and push to the image stream

without DB connection

Build and run the application locally with Docker

Build the application and push to the image stream

Deploy application on the ARO 4 cluster

with DB from web console

Deploy the application from the web console

with DB from CLI

Deploy the application from CLI

without DB from web console

Deploy the application from the web console

Delete the application from the web console

without DB from CLI

Deploy the application from CLI

Delete the application from CLI

Clean up resources

Next steps

Files

howto-deploy-java-liberty-app.md

Latest commit

History

howto-deploy-java-liberty-app.md

File metadata and controls

Deploy a Java application with Open Liberty/WebSphere Liberty on an ARO cluster

Prerequisites

Install the Open Liberty OpenShift Operator

Create an OpenShift namespace for the Java app

Create an Azure Database for MySQL

Prepare the Liberty application

Run the application on Open Liberty

Check out the application

Build project

Test your application locally

Prepare the application image

Build the application and push to the image stream

Build and run the application locally with Docker

Build the application and push to the image stream

Deploy application on the ARO 4 cluster

Deploy the application from the web console

Deploy the application from CLI

Deploy the application from the web console

Delete the application from the web console

Deploy the application from CLI

Delete the application from CLI

Clean up resources

Next steps