Installation note for WebSphere Application Server Liberty 23.X

Overview

Requirements

• Java SE 17 or 21 LTS. It is recommended using IBM Semeru, or Eclipse Temurin Java distributions.

• WebSphere Application Server Liberty 23.0.0.12 or higher for Jakarta EE 10

• Database and JDBC driver

• EBX® CD

• No CDI features in EBX®'s additional modules (since CDI will be automatically disabled)

WebSphere Application Server Liberty installation

This quick installation example is performed for a Linux operating system.

1. Download WebSphere Application Server Liberty 23.X latest version (zip distribution) from:

   https://www.ibm.com/support/pages/230012-websphere-application-server-liberty-230012 .

   The following example uses Liberty with Jakarta EE 10 Web Profile zip distribution.

2. Extract the content of this package to a directory on your local machine.

3. Create a new application server (example: 'ebxServer') by running the command:

   <WLP_HOME>/wlp/bin/server create ebxServer

4. Edit <WLP_HOME>/usr/servers/<SERVER_NAME>/server.xmlfile. In our example, <SERVER_NAME> is 'ebxServer'.

   • Replace the <feature>webProfile-10.0</feature> tag with, at least, the following lines:

     <feature>mail-2.0</feature>
     <feature>jdbc-4.2</feature>
     <feature>jndi-1.0</feature>
     <feature>servlet-5.0</feature>
     

   • Add the following line into the <server> tag:

     <webContainer deferServletLoad="false"  allowQueryParamWithNoEqual="true"/>

     Note

     The deferServletLoad attribute must be set to false since EBX® requires servlets to be initialized on application server startup. By default, WebSphere Application Server Liberty defers servlets loading until a request is received for the associated web application. See Specifying when servlets are loaded and initialized for more information.

     Note

     The allowQueryParamWithNoEqual attribute must be set to true since, according to the Servlet API specification, a value of a request parameter must be returned as a String, or null if the parameter does not exist. Thus, EBX® expects a non null value for an existing request parameter.

EBX® home directory configuration

1. Create the EBX_HOME directory, for example /opt/ebx/home.

2. Copy from the EBX® CD, the ebx.software/files/ebx.properties file to EBX_HOME. In our example, we will have the following file:

   /opt/ebx/home/ebx.properties.

3. If needed, edit the ebx.properties file to override the default database. By default the standalone H2 database is defined. The property key ebx.persistence.factory must be uncommented for other supported databases and the h2.standalone one must be commented.

EBX® and third-party libraries deployment

1. Create the EBX_LIB directory. For example, /opt/ebx/home/lib.

2. Copy third-party libraries from the EBX® CD, or from other sources, to the EBX_LIB directory. In our example and for a PostgreSQL database, we will get:

   postgresql-X.X.X-driver.jar, coming from another source than the EBX® CD.

   ebx-lz4.jar, coming from the ebx.software/lib/ directory of the EBX® CD.

   The complete description of these components is given in the chapter Jakarta EE deployment. If those components are already deployed on the class-loading system, they do not have to be duplicated (ex: jakarta.mail 2.0.X is already present since mail-2.0 feature has been activated for this server).

JNDI entries configuration

1. For JMS configuration on WebSphere Application Server Liberty, see Configuring JMS connection factories.

2. For Java Mail configuration on WebSphere Application Server Liberty, see Administering JavaMail on Liberty.

Data source and JDBC provider configuration

1. To create the JDBC driver library, edit the <WLP_HOME>/usr/servers/<SERVER_NAME>/server.xml file by adding the following lines into the <server> tag:

   <library id="jdbcDriver">
     <file name="${EBX_LIB}/To be completed"/>
   </library>

   Caution: the name attribute value, from the file tag, has to be completed. In our example, it should be ${EBX_LIB}/postgresql-X.X.X-driver.jar.

2. To create the JDBC data source, edit the same file and same XML tag by adding the following lines:

   <dataSource id="ebxRepository" jndiName="jdbc/EBX_REPOSITORY">
     <jdbcDriver libraryRef="jdbcDriver"/>
     <properties.toBeCompleted/>
   </dataSource>

   Caution: the properties tag, has to be completed. Since the kind of tag is strongly reliant on the JDBC driver used, a default configuration can not be provided. For a PostgreSQL driver, it may looks like:

   <properties.postgresql databaseName="EBXDB" serverName="localhost" portNumber="5432" user="ebx" password="ebx"/>

   Note

   To hide the password for a JDBC connection in the server.xml file of WebSphere Application Server Liberty, refer to Authentication Data (authData), containerAuthData from Data Source (dataSource) and Securing Liberty and its applications.

   Note

   The data source can also be specified through the EBX® main configuration file. See Data source of the EBX® repository for more information.

Java Virtual Machine configuration

1. Set server's environment variables by adding the following lines into <WLP_HOME>/usr/servers/<SERVER_NAME>/server.env file:

   EBX_HOME="<path_to_the_directory_ebx_home>"
   EBX_LIB="<path_to_the_directory_ebx_lib>"
   JAVA_HOME="<path_to_the_java_home>"
   

2. Set Java options by creating a new jvm.options file under the <WLP_HOME>/usr/servers/<SERVER_NAME>/ directory. This file will hold, at least, the following lines:

   -Debx.home="${EBX_HOME}"
   -Debx.properties="${EBX_HOME}/ebx.properties"

EBX® application deployment

1. Create the <EBX_HOME>/ear/ directory.

2. Copy from the EBX® CD, the ebx.software/webapps/ear-packaging/EBX.ear to the <EBX_HOME>/ear/ directory. In our example, we will get:

   /opt/ebx/home/ear/EBX.ear

3. To create the EBX® compression library reference, edit the <WLP_HOME>/usr/servers/<SERVER_NAME>/server.xml file by adding the following lines into the <server> tag:

   <library id="ebxLibLz4">
     <file name="${EBX_LIB}/ebx-lz4.jar"/>
   </library>

   Note

   WebSphere Application Server Liberty doesn't support LZ4 JNI implementation.

4. To deploy EBX.ear, edit the <WLP_HOME>/usr/servers/<SERVER_NAME>/server.xml file by adding the following lines into the <server> tag:

   <application id="ebxApp" location="${EBX_HOME}/ear/EBX.ear" name="ebxApp" type="ear">
     <classloader commonLibraryRef="ebxLibLz4" />
   </application>

EBX® application start

1. After the launch of the WebSphere Application Server Liberty, with the <WLP_HOME>/wlp/bin/server start ebxServer command line, run the EBX® web application by entering the following URL in the browser:

   http://localhost:9080/ebx/

2. At first launch, EBX® Wizard helps to configure the default properties of the initial repository.