Chapter 3. Developing and deploying Thorntail application
In addition to using an example, you can create new Thorntail applications from scratch and deploy them to OpenShift.
3.1. Creating an application from scratch
Creating a simple Thorntail–based application with a REST endpoint from scratch.
Prerequisites
- OpenJDK 8 or OpenJDK 11 installed
- Maven 3.6.0 installed
Procedure
Create a directory for the application and navigate to it:
$ mkdir myApp $ cd myApp
We recommend you start tracking the directory contents with Git. For more information, see Git tutorial.
In the directory, create a
pom.xml
file with the following content.<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>restful-endpoint</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>war</packaging> <name>Thorntail Example</name> <properties> <version.thorntail>2.7.3.Final-redhat-00001</version.thorntail> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <failOnMissingWebXml>false</failOnMissingWebXml> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <!-- Specify the JDK builder image used to build your application. --> <jkube.generator.from>registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift:latest</jkube.generator.from> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>io.thorntail</groupId> <artifactId>bom</artifactId> <version>${version.thorntail}</version> <scope>import</scope> <type>pom</type> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>io.thorntail</groupId> <artifactId>jaxrs</artifactId> </dependency> </dependencies> <build> <finalName>restful-endpoint</finalName> <plugins> <plugin> <groupId>io.thorntail</groupId> <artifactId>thorntail-maven-plugin</artifactId> <version>${version.thorntail}</version> <executions> <execution> <goals> <goal>package</goal> </goals> </execution> </executions> </plugin> </plugins> </build> <!-- Specify the repositories containing RHOAR artifacts --> <repositories> <repository> <id>redhat-ga</id> <name>Red Hat GA Repository</name> <url>https://maven.repository.redhat.com/ga/</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>redhat-ga</id> <name>Red Hat GA Repository</name> <url>https://maven.repository.redhat.com/ga/</url> </pluginRepository> </pluginRepositories> </project>
Create a directory structure for your application:
mkdir -p src/main/java/com/example/rest
In the
src/main/java/com/example/rest
directory, create the source files:HelloWorldEndpoint.java
with the class that serves the HTTP endpoint:package com.example.rest; import javax.ws.rs.Path; import javax.ws.rs.core.Response; import javax.ws.rs.GET; import javax.ws.rs.Produces; @Path("/hello") public class HelloWorldEndpoint { @GET @Produces("text/plain") public Response doGet() { return Response.ok("Hello from Thorntail!").build(); } }
RestApplication.java
with the application context:package com.example.rest; import javax.ws.rs.core.Application; import javax.ws.rs.ApplicationPath; @ApplicationPath("/rest") public class RestApplication extends Application { }
Execute the application using Maven:
$ mvn thorntail:run
Results
Accessing the http://localhost:8080/rest/hello
URL in your browser should return the following message:
Hello from Thorntail!
After finishing the procedure, there should be a directory on your hard drive with the following contents:
myApp ├── pom.xml └── src └── main └── java └── com └── example └── rest ├── HelloWorldEndpoint.java └── RestApplication.java
3.2. Deploying Thorntail application to OpenShift
To deploy your Thorntail application to OpenShift, configure the pom.xml
file in your application and then use the OpenShift Maven plugin.
The Fabric8 Maven plugin is no longer supported. Use the OpenShift Maven plugin to deploy your Thorntail applications on OpenShift. For more information, see the section migrating from Fabric8 Maven Plugin to Eclipse JKube.
You can specify a Java image by replacing the jkube.generator.from
URL in the pom.xml
file. The images are available in the Red Hat Ecosystem Catalog.
<jkube.generator.from>IMAGE_NAME</jkube.generator.from>
For example, the Java image for RHEL 7 with OpenJDK 8 is specified as:
<jkube.generator.from>registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift:latest</jkube.generator.from>
3.2.1. Supported Java images for Thorntail
Thorntail is certified and tested with various Java images that are available for different operating systems. For example, Java images are available for RHEL 7 and RHEL 8 with OpenJDK 8 or OpenJDK 11. Similar images are available on IBM Z and IBM Power Systems.
You require Docker or podman authentication to access the RHEL 8 images in the Red Hat Ecosystem Catalog.
The following table lists the images supported by Thorntail for different architectures. It also provides links to the images available in the Red Hat Ecosystem Catalog. The image pages contain authentication procedures required to access the RHEL 8 images.
3.2.1.1. Images on x86_64 architecture
OS | Java | Red Hat Ecosystem Catalog |
---|---|---|
RHEL 7 | OpenJDK 8 | |
RHEL 7 | OpenJDK 11 | |
RHEL 8 | OpenJDK 8 | |
RHEL 8 | OpenJDK 11 |
The use of a RHEL 8-based container on a RHEL 7 host, for example with OpenShift 3 or OpenShift 4, has limited support. For more information, see the Red Hat Enterprise Linux Container Compatibility Matrix.
3.2.1.2. Images on s390x (IBM Z) architecture
OS | Java | Red Hat Ecosystem Catalog |
---|---|---|
RHEL 8 | Eclipse OpenJ9 11 |
3.2.1.3. Images on ppc64le (IBM Power Systems) architecture
OS | Java | Red Hat Ecosystem Catalog |
---|---|---|
RHEL 8 | Eclipse OpenJ9 11 |
The use of a RHEL 8-based container on a RHEL 7 host, for example with OpenShift 3 or OpenShift 4, has limited support. For more information, see the Red Hat Enterprise Linux Container Compatibility Matrix.
3.2.2. Preparing Thorntail application for OpenShift deployment
For deploying your Thorntail application to OpenShift, it must contain:
-
Launcher profile information in the application’s
pom.xml
file.
In the following procedure, a profile with OpenShift Maven plugin is used for building and deploying the application to OpenShift.
Prerequisites
- Maven is installed.
- Docker or podman authentication into Red Hat Ecosystem Catalog to access RHEL 8 images.
Procedure
Add the following content to the
pom.xml
file in the application root directory:... <profiles> <profile> <id>openshift</id> <build> <plugins> <plugin> <groupId>org.eclipse.jkube</groupId> <artifactId>openshift-maven-plugin</artifactId> <version>1.1.0</version> <executions> <execution> <goals> <goal>resource</goal> <goal>build</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </profile> </profiles>
Replace the
jkube.generator.from
property in thepom.xml
file to specify the OpenJDK image that you want to use.x86_64 architecture
RHEL 7 with OpenJDK 8
<jkube.generator.from>registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift:latest</jkube.generator.from>
RHEL 7 with OpenJDK 11
<jkube.generator.from>registry.access.redhat.com/openjdk/openjdk-11-rhel7:latest</jkube.generator.from>
RHEL 8 with OpenJDK 8
<jkube.generator.from>registry.redhat.io/openjdk/openjdk-8-rhel8:latest</jkube.generator.from>
RHEL 8 with OpenJDK 11
<jkube.generator.from>registry.redhat.io/openjdk/openjdk-11-rhel8:latest</jkube.generator.from>
s390x (IBM Z) architecture
RHEL 8 with Eclipse OpenJ9 11
<jkube.generator.from>registry.access.redhat.com/openj9/openj9-11-rhel8:latest</jkube.generator.from>
ppc64le (IBM Power Systems) architecture
RHEL 8 with Eclipse OpenJ9 11
<fabric8.generator.from>registry.access.redhat.com/openj9/openj9-11-rhel8:latest</fabric8.generator.from>
3.2.3. Deploying Thorntail application to OpenShift using OpenShift Maven plugin
To deploy your Thorntail application to OpenShift, you must perform the following:
- Log in to your OpenShift instance.
- Deploy the application to the OpenShift instance.
Prerequisites
-
oc
CLI client installed. - Maven installed.
Procedure
Log in to your OpenShift instance with the
oc
client.$ oc login ...
Create a new project in the OpenShift instance.
$ oc new-project MY_PROJECT_NAME
Deploy the application to OpenShift using Maven from the application’s root directory. The root directory of an application contains the
pom.xml
file.$ mvn clean oc:deploy -Popenshift
This command uses the OpenShift Maven plugin to launch the S2I process on OpenShift and start the pod.
Verify the deployment.
Check the status of your application and ensure your pod is running.
$ oc get pods -w NAME READY STATUS RESTARTS AGE MY_APP_NAME-1-aaaaa 1/1 Running 0 58s MY_APP_NAME-s2i-1-build 0/1 Completed 0 2m
The
MY_APP_NAME-1-aaaaa
pod should have a status ofRunning
once it is fully deployed and started.Your specific pod name will vary.
Determine the route for the pod.
Example Route Information
$ oc get routes NAME HOST/PORT PATH SERVICES PORT TERMINATION MY_APP_NAME MY_APP_NAME-MY_PROJECT_NAME.OPENSHIFT_HOSTNAME MY_APP_NAME 8080
The route information of a pod gives you the base URL which you use to access it.
In this example,
http://MY_APP_NAME-MY_PROJECT_NAME.OPENSHIFT_HOSTNAME
is the base URL to access the application.Verify that your application is running in OpenShift.
$ curl http://MY_APP_NAME-MY_PROJECT_NAME.OPENSHIFT_HOSTNAME/rest/hello Hello from Thorntail!
3.3. Deploying Thorntail application to stand-alone Red Hat Enterprise Linux
To deploy your Thorntail application to stand-alone Red Hat Enterprise Linux, configure the pom.xml
file in the application, package it using Maven and deploy using the java -jar
command.
Prerequisites
- RHEL 7 or RHEL 8 installed.
3.3.1. Preparing Thorntail application for stand-alone Red Hat Enterprise Linux deployment
For deploying your Thorntail application to stand-alone Red Hat Enterprise Linux, you must first package the application using Maven.
Prerequisites
- Maven installed.
Procedure
Add the following content to the
pom.xml
file in the application’s root directory:... <build> <plugins> <plugin> <groupId>io.thorntail</groupId> <artifactId>thorntail-maven-plugin</artifactId> <version>${version.thorntail}</version> <executions> <execution> <goals> <goal>package</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ...
Package your application using Maven.
$ mvn clean package
The resulting JAR file is in the
target
directory.
3.3.2. Deploying Thorntail application to stand-alone Red Hat Enterprise Linux using jar
To deploy your Thorntail application to stand-alone Red Hat Enterprise Linux, use java -jar
command.
Prerequisites
- RHEL 7 or RHEL 8 installed.
- OpenJDK 8 or OpenJDK 11 installed.
- A JAR file with the application.
Procedure
Deploy the JAR file with the application.
$ java -jar my-app-thorntail.jar
Verify the deployment.
Use
curl
or your browser to verify your application is running athttp://localhost:8080
:$ curl http://localhost:8080