Cloud Software Group, Inc. EBX®
Documentation > Administration Guide > Installation & configuration > Installation notes
Navigation mode Documentation > Administration Guide > Installation & configuration > Installation notes

# Installation note for WebSphere Application Server Liberty 23.X

## Overview

##### Attention

- This chapter describes a quick installation example of TIBCO EBX® on WebSphere Application Server Liberty.

- It does not replace the documentation of this application server.

- They are not general installation recommendations, as the installation process is determined by architectural decisions, such as the technical environment, application mutualization, delivery process, and organizational decisions.

- The complete description of the components needed by EBX® is given in the chapter Jakarta EE deployment.

- To avoid unpredictable behavior, the guideline to follow is to avoid any duplicates of `ebx.jar`, `ebx-lz4.jar`, or other libraries in the class-loading system.

- The description below uses the variable name <WLP_HOME> to refer to the WebSphere Application Server Liberty installation directory, and from which relative paths are resolved.

- Refer to the Security Best Practices for information on navigating secure deployments.

## 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)

##### See also

- Supported environments

## 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.xml`file. 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.

Documentation > Administration Guide > Installation & configuration > Installation notes