Article

How JBoss EAP 8 Beta simplifies external database config

March 27, 2023
Java
phil
Philip Hayes
Principal Technical Marketing Manager
Featured image for Red Hat JBoss Enterprise Application Platform.

In this article, we will demonstrate how to deploy a complex Red Hat JBoss Enterprise Application Platform application using the datasources feature pack to deploy the required drivers and configuration to connect to a PostgreSQL database. The datasources feature pack for JBoss Enterprise Application Platform (EAP) and JBoss EAP XP makes it easy to configure JBoss EAP with JDBC drivers and data sources for various databases such as Oracle, Microsoft SQL Server, and PostgreSQL.

This is a follow-up to the previous article How JBoss EAP 8 Beta makes deployment on OpenShift easier, where we demonstrated provisioning a simple hello world JBoss EAP 8 Beta application for Red Hat OpenShift using the eap-maven-plug-in.

This article covers the following topics:

  • How to include the Maven configuration necessary to provision and configure a JBoss EAP instance to run our application.
  • How to build and deploy the application connecting to a locally running PostgreSQL database.
  • How to use Helm charts to build and deploy the application to OpenShift and connect to a PostgreSQL database running on the same cluster.

Set up the prerequisites

To perform the steps described in this article, you will need the following components.

Check out the sample application from this GitHub repository.

Before we start any of our configuration or code changes, we're going to run a PostgreSQL container on our local machine by running the following command in a terminal:

podman run --name myPostgresDb \
   -p 5432:5432 \
   -e POSTGRES_USER=postgresUser \
   -e POSTGRES_PASSWORD=postgresPW \
   -e POSTGRES_DB=postgresDB \
   -d postgres

Step 1: Change the configuration

To build and deploy this application on OpenShift, the only change we need to make is to the Maven pom.xml file. This involves adding the eap-maven-plugin, which takes care of all the provisioning and configuration required to build an instance of JBoss EAP 8 Beta to run our application.

It's worth comparing this single step to the multiple steps involved with performing the same task for a JBoss EAP 7 application on OpenShift, as described in the article How to migrate your Java applications.

Similarly, to run the application in their local environment for JBoss EAP 7, perform the following steps:

  • Create the .war file (with the mvn package from the project).
  • Download JBoss EAP 7.4.
  • Download and apply patches to get an updated JBoss EAP 7.4.
  • Download the JDBC drivers and put them in the JAR and module.xml in the server.
  • Run CLI commands or edit standalone.xml to configure the data source.
  • Start the server with ./standalone.sh.
  • Deploy the application.

For JBoss EAP 8, simply run a single Maven command, and the entire process runs.

Let's try this out in our local environment.

Open the pom.xml file and add the following before the closing tag:

   <profile>
           <id>openshift</id>
           <build>
               <plugins>
                   <plugin>
                       <groupId>org.apache.maven.plugins</groupId>
                       <artifactId>maven-war-plugin</artifactId>
                       <version>3.3.2</version>
                       <configuration>
                           <warName>ROOT</warName>
                           <failOnMissingWebXml>false</failOnMissingWebXml>
                           </configuration>
                   </plugin>
                   <plugin> 
                       <groupId>org.jboss.eap.plugins</groupId>
                       <artifactId>eap-maven-plugin</artifactId>
                       <version>1.0.0.Beta6-redhat-00001</version>
                       <configuration>
                           <channels>
                               <channel>
                                   <groupId>org.jboss.eap.channels</groupId>
                                   <artifactId>eap-8.0-beta</artifactId>
                               </channel>
                           </channels>
                           <feature-packs>
                               <feature-pack>
                                   <location>org.jboss.eap:wildfly-ee-galleon-pack</location>
                               </feature-pack>
                               <feature-pack>
                                   <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location>
                               </feature-pack>
                               <feature-pack>
                                   <location>org.jboss.eap:eap-datasources-galleon-pack</location>
                               </feature-pack>
                           </feature-packs>
                           <layers>
                               <layer>cloud-server</layer>
                               <layer>postgresql-datasource</layer>
                               <layer>ejb</layer>
                               <layer>jsf</layer>
                           </layers>
                           <filename>ROOT.war</filename>
                       </configuration>
                       <executions>
                           <execution>
                               <goals>
                                   <goal>package</goal>
                               </goals>
                           </execution>
                       </executions>
                   </plugin>
               </plugins>
           </build>
       </profile>

If we examine the pom.xml snippet, we can see the inclusion of three feature packs:

  • wildfly-ee-galleon-pack: The wildfly-ee-galleon-pack contains the features required to build an instance of JBoss EAP. This feature pack contains several layers (e.g., jaxrs-server and cloud-server).
  • eap-cloud-galleon-pack: You can find more information about this feature pack. The main features are as follows:
    • Server startup scripts: When starting an EAP server that was provisioned by the cloud feature-pack, a set of bash scripts are executed in order to adjust the server configuration. These scripts configure a range of server functions such as clustering, security, logging, messaging, tracing, and config management. Read more on this.
    • Adjustment of WildFly Galleon layers to tune for deployment on OpenShift, for example, disabling the management console. Read more on this.
    • Automatic provisioning of the health subsystem allows for server state monitoring and provides liveness and readiness probes.
    • Automatic routing of server logs to the console to ensure they are visible in the pod logs in the OpenShift console.
  • eap-datasources-galleon-pack: This feature pack for JBoss EAP and JBoss EAP Expansion Pack provides JDBC drivers and data sources for the following databases:
  • Microsoft SQL Server
  • Oracle
  • PostgreSQL

We can also see the inclusion of four layers in our pom.xml file snippet:

  • cloud-server: The cloud server layer is an extension of the jaxrs-server and datasources-web-server layers providing cloud-native functionality such as observability and jms-activemq.
  • postgresql-datasource: Adds support for postgresql database drivers, requires the eap-datasources-galleon-pack feature pack.
  • ejb: Adds support for Jakarta Enterprise Beans, excluding the IIOP protocol.
  • jsf: Adds support for Jakarta Server Faces.

The addition of datasources feature pack and postgresql-datasource layer will instruct the eap-maven-plugin to install and configure a data source to connect to a PostgreSQL database. If we look at the documentation for the PostgresSQL layer, we can see the need for a POSTGRESQL_DRIVER_VERSION build time environment variable. This build time environment variable is mandatory and tells the eap-maven-plugin which version of the PostgreSQL driver to install.

Step 2: Test the application locally

Once this configuration is added, we can now test our application locally using the eap-maven-plugin to provision a JBoss EAP server. Before we do this, we need to set a few environment variables.

As we mentioned in the previous section, we need to tell the eap-maven-plugin which version of the PostgreSQL driver to install with the POSTGRESQL_DRIVER_VERSION environment variable.

export POSTGRESQL_DRIVER_VERSION=42.2.19

We can provision our local instance of JBoss EAP with the required feature pack and layers with the following command:

mvn clean package -Popenshift

This command does many things, such as:

  • Build the Java application.
  • Provision a JBoss EAP server with all the capabilities that the application requires.
  • Deploy the application in the server.

You can then run the application from the ./target/server folder because the build artifact is already deployed to the server. This is a big difference from the JBoss EAP 7 workflow, where users have to package their app and then deploy it in a running JBoss EAP.

Before we start our JBoss EAP instance, we will need runtime environment variables to configure the connection to our local instance of PostgreSQL. These should match the variables passed to our PostgreSQL container by our podman run command from the prerequisites section:

export POSTGRESQL_DATABASE=postgresDB \
&& export POSTGRESQL_USER=postgresUser \
&& export POSTGRESQL_PASSWORD=postgresPW \
&& export POSTGRESQL_DATASOURCE=postgresql \
&& export POSTGRESQL_SERVICE_HOST=127.0.0.1 

We can now run our application deployed in JBoss EAP with the following command:

./target/server/bin/standalone.sh

Then open our browser at http://127.0.0.1:8080. We should see a UI, as shown in Figure 1.

Screenshot of kitchensink application running on localhost.
Figure 1: The kitchensink application running on localhost.

Now that we have successfully configured our application and deployed a local instance, we can test what will be provisioned during the OpenShift Source-to-Image (S2I) build process when deploying our application to OpenShift.

Step 3: Build and deploy on OpenShift

Before we start the build process on OpenShift, we will need a PostgreSQL database. Follow these steps:

  • Log in to the OpenShift console.
  • From the developer UI, click on Add.
  • Select Database from the developer catalog.
  • Choose PostgreSQL (Ephemeral), as shown in Figure 2.
OpenShift database catalog
Figure 2: OpenShift database catalog.
  • Click on Instantiate Template and populate the resulting form as shown in Figure 3.
The PostgreSQL template form.
Figure 3: Complete the PostgreSQL template form.
  • For reference, the two field values we're changing are:
    • Database Service Name: eap-sample-db
    • PostgreSQL Database Name: sample-db
  • Click on Create to create the PostgreSQL database instance.
  • We can now deploy our EAP 8 Beta application with Helm.
  • Click on Add+.
  • Select Helm Chart from the developer catalog.
  • Enter eap8 in the Filter by keyword field as shown in Figure 4.
Select the JBoss EAP 8 Helm chart from the catalog.
Figure 4: Select the JBoss EAP 8 Helm chart from the catalog.

Note: For the purpose of this article, we've already created a version of this application with the eap-maven-plug configuration added to the pom.xml file. In the next step, we'll reference this version in the sample-app-eap8-ocp folder.

  • Select Eap8.
  • Click on Install Helm Chart.
  • Switch to YAML view.
  • Delete the existing content.
  • Paste the following YAML:
build:
 uri: https://github.com/deewhyweb/eap7-eap8-migration-workshop.git
 ref: main
 contextDir: sample-app-eap8-ocp
 env:
   - name: POSTGRESQL_DRIVER_VERSION
     value: '42.5.1'
deploy:
 replicas: 1
 env:
   # Env vars to connect to PostgreSQL DB
   - name: POSTGRESQL_DATABASE
     valueFrom:
       secretKeyRef:
         key: database-name
         name: eap-sample-db
   - name: POSTGRESQL_USER
     valueFrom:
       secretKeyRef:
         key: database-user
         name: eap-sample-db
   - name: POSTGRESQL_PASSWORD
     valueFrom:
       secretKeyRef:
         key: database-password
         name: eap-sample-db
   - name: POSTGRESQL_DATASOURCE
     value: postgresql
   - name: POSTGRESQL_SERVICE_HOST
     value: eap-sample-db

Note: There are a few things to point out in this Helm configuration. We have defined a build time variable POSTGRESQL_DRIVER_VERSION to determine how the PostgreSQL driver version is passed to the eap-maven-plugin when S2I builds the application image. Runtime environment variables (such as user credentials) are read from a secret created when the database is instantiated. So application configuration can be safely stored in Git without any sensitive information.

  • Click on Install and you will be taken to the topology view, as shown in Figure 5.
OpenShift topology view
Figure 5: OpenShift topology view.

Two build-configs are created by this Helm chart: an artifacts build and a runtime build. When the second build is complete, the application will be deployed. The application is running when the pod donut around the JBoss EAP logo is dark blue (i.e., the pods are in a running state).

It will take a while to build and deploy the application. To monitor the progress, follow these steps.

  • Go to Builds. 
  • Select eap8-build-artifacts.
  • Choose the Builds tab.
  • Click on eap8-build-artifacts-1 to view the logs of the active build.
  • Once the builds are complete, you will be able to click the Open URL icon of the eap8 deployment to view the running application.

A simple configuration

In this article, we added the eap-maven-plugin to an existing JBoss EAP 8-Beta project to enable the provisioning of a JBoss EAP instance, including integration to a PostgreSQL database. Then we used the JBoss EAP 8 Helm chart to build and deploy this image on OpenShift.

The data sources feature pack for JBoss EAP and JBoss EAP XP makes it easy to configure JBoss EAP with JDBC drivers and data sources for various databases. The developer experience for local development and OpenShift configuration has also improved, making it far easier to set up a local environment and ensure successful deployment on OpenShift.

Last updated: October 31, 2023