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

# Jakarta EE deployment

## Introduction

This chapter details deployment specifications for TIBCO EBX® on a Java application server. For specific information regarding supported application servers and inherent limitations, see Supported environments.

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

## Software components

EBX® uses the following components:

- Library `ebx.jar`

- Embedded and required third-party Java libraries

- EBX® built-in web applications and optional custom web applications

- EBX® main configuration file

- EBX® repository

- Default user and roles directory, integrated within the EBX® repository, or a third-party system (LDAP, RDBMS) for the user authentication

##### See also

- Supported environments

## Embedded third-party libraries

To increase EBX® independence and interoperability, it embeds its own third-party libraries. Even if some of them have been modified, preventing conflicts, others must remain unchanged since they are official Java APIs.

The ones that can produce conflicts are:

- Apache Geronimo JSON

- Apache Geronimo JSON Bind

- Jakarta Activation API

- Jakarta Annotations API

- Jakarta JSON API

- Jakarta JSON Binding

- Jakarta Transaction API

- Jakarta WS RS

- Jakarta XML Bind

- Jakarta XML SOAP messaging API

- Jakarta XML WS API

- LZ4 compression for Java

- MicroProfile OpenAPI

For more information regarding the versions or the details of the Third-Party Library, please refer to the: `TIB_ebx_6.2.1_license.pdf`.

Since those libraries are already integrated, custom web applications should not include them anew, otherwise linkage errors can occur. Furthermore, they should not be deployed aside from the `ebx.jar` library for the same reasons.

## Required third-party libraries

EBX® requires several third-party Java libraries. These libraries must be deployed and be accessible from the class-loader of `ebx.jar`. Depending on the application server and the Java runtime environment being used, these libraries may already be present or may need to be added manually.

### Data compression library

The library named `ebx-lz4.jar` must be deployed separately from `ebx.jar`. It contains several compression implementations: JNI dedicated architecture libraries and Java fallbacks. It is possible to ensure optimal compression and decompression performance for EBX® repository by following prerequisites. If prerequisites can not be validated, EBX® will function in Java fallbacks safe or unsafe, but its performance will be degraded. The default location for `ebx-lz4.jar` library is beside `ebx.jar`.

To verify the compression implementation actually used by the EBX® repository, please check the value of 'Compression' in 'Administration > System Information', section 'Repository information'. It should be '`JNI - validated`' for optimal performance. Otherwise, it will be '`Java[Safe|Unsafe] - validated`' for Java fallbacks.

#### Performance prerequisites

The JNI access is allowed to the following operating system architectures: `i386`, `x86`, `amd64`, `x86_64`, `aarch64` or `ppc64le`. To verify this value, please check the value of 'Operating system architecture' in 'Administration > System Information', section 'System information'.

To enable JNI access for `ebx-lz4.jar`, the library should be loaded by the system class loader (also known as the application class loader). The deployment may be done by following the specific instructions for your application server.

### Database drivers

The EBX® repository requires a database. Generally, the required driver is configured along with a data source, if one is used. Depending on the database defined in the main configuration file, one of the following drivers is required. Keep in mind that, whichever database you use, the version of the JDBC client driver must be equal to or higher than the version of the database server.

H2 | Version 2.2.224 validated. Note that H2 is not supported in production environments. https://www.h2database.com/ If the H2 repository has been built with version 1.0 driver, this migration to v2 process must be applied.
Oracle JDBC | Oracle database 21c is validated on their latest patch set update. Determine the driver that should be used according to the database server version and the Java runtime environment version. Download the `ojdbc11.jar` certified library with JDK 17 or 21. Oracle database JDBC drivers download.
SQL Server JDBC | SQL Server 2012 SP4 and greater, with all corrective and maintenance patches applied, are validated. Remember to use an up-to-date JDBC driver, as some difficulties have been encountered with older versions. For example, include the `mssql-jdbc-12.6.1.jre11.jar` library, depending on the Java runtime environment version you use. Download Microsoft JDBC Driver 12.6.1 for SQL Server (zip).
PostgreSQL | PostgreSQL Java 8 validated Include the latest JDBC driver version 4.2 released for your database server and Java runtime environment. PostgreSQL JDBC drivers download.

##### See also

- Data source of the EBX® repository
- Configuring the EBX® repository

### SMTP and emails

According to the web application server being used, the library `Jakarta Mail API` for email management may already be provided, or must be added manually.

EBX® requires a library that is compatible with version 2.0.1 of this API. See Activating and configuring SMTP and emails for more information on the configuration.

To facilitate manual installation, the `jakarta.mail-2.0.1.jar` has been provided and placed under the `ebx.software/lib/lib-mail` directory.

##### See also

- Jakarta Mail 2.0

### Secure Socket Layer (SSL)

SSL features activation, configuration, and management are tightly linked to the web application server used. Consequently, you should refer to the appropriate web application server documentation. For example, Tomcat SSL/TLS Configuration How-To.

##### See also

- TIBCO EBX® main configuration file

### Java Message Service (JMS)

When using JMS, version 3.0.0 or higher is required.

Depending on whether a Jakarta EE application server or a Servlet/Java Server Pages (JSP) implementation is being used, the library required is as follows:

- For an application server based on Jakarta EE (Enterprise Edition), the required JMS provider library is available by default. See https://jakarta.ee/specifications/platform/ for more information.

- For a Servlet/Java Server Pages (JSP) implementation using Java SE (Java Platform Standard Edition), for example Apache Tomcat, a JMS provider library such as Apache ActiveMQ may need to be added. See https://www.oracle.com/java/technologies/java-se-glance.html for more information.

##### Note

In EBX®, the supported JMS model is exclusively Point-to-Point (PTP). PTP systems allow working with queues of messages.

##### See also

- TIBCO EBX® main configuration file

## Web applications

EBX® provides pre-packaged EARs that can be deployed directly if your company has no custom EBX® module web applications to add. If deploying custom web applications as EBX® modules, it is recommended to rebuild an EAR containing the custom modules packaged at the same level as the built-in web applications.

##### Attention

Web application deployment on `/` path context is no more supported. The path context must not be empty nor equals to `/`. Moreover, web applications deployment on paths of different depth is deprecated. Every web application path context must be set on the same path depth.

For more information, see the note on repackaging the EBX® EAR at the end of this chapter.

### EBX® built-in web applications

EBX® includes the following built-in web applications.

Web application name | Description | Required
--- | --- | ---
`ebx` | EBX® entry point, which handles the initialization on start up. See Deployment details for more information. | Yes
`ebx-root-1.0` | EBX® root web application. Any application that uses EBX® requires the root web application to be deployed. | Yes
`ebx-ui` | EBX® user interface web application. | Yes
`ebx-authentication` | EBX® authentication application. | Yes
`ebx-manager` | EBX® user interface web application. | Yes
`ebx-dma` | EBX® data model assistant, which helps with the creation of data models through the user interface. Note: The data model assistant requires the `ebx-manager` user interface web application to be deployed. | Yes
`ebx-dataservices` | EBX® data services web application. Data services allow external interactions with the EBX® repository using the SOAP operations and Web Services Description Language WSDL generation standards or using the Built-in RESTful services. Note: The EBX® web service generator requires the deployment of the `ebx-manager` user interface web application. | Yes
`ebx-ide` | EBX® Integrated Development Environment web application. | Yes
`ebx-hub` | EBX® Hub web application. | No

### Custom web applications

It is possible to extend and customize the behavior of EBX® by deploying custom web applications which conform to the EBX® module requirements.

##### See also

- Packaging TIBCO EBX® modules
- Declaring modules as undeployed

## Deployment details

### Introduction

This section describes the various options available to deploy the '`ebx`' web application. These options are available in its deployment descriptor (`WEB-INF/web.xml`) and are complemented by the properties defined in the main configuration file.

##### Attention

For JBoss application servers, any unused resources must be removed from the `WEB-INF/web.xml` deployment descriptor.

##### See also

- TIBCO EBX® main configuration file
- Supported application servers

### User interface and web access

The web application '`ebx`' (packaged as `ebx.war`) contains the servlet `FrontServlet`, which handles the initialization and serves as the sole user interface entry point for the EBX® web tools.

#### Configuring the deployment descriptor for 'FrontServlet'

In the file `WEB-INF/web.xml` of the web application '`ebx`', the following elements must be configured for `FrontServlet`:

`/web-app/servlet/load-on-startup` | To ensure that `FrontServlet` initializes upon EBX® start up, the `web.xml` deployment descriptor must specify the element `<load-on-startup>1</load-on-startup>`.
`/web-app/servlet-mapping/url-pattern` | `FrontServlet` must be mapped to the path '`/`'.

#### Configuring the application server for 'FrontServlet'

`FrontServlet` must be authorized to access other contexts, such as `ServletContext`.

For example, on Tomcat, this configuration is performed using the attribute `crossContext` in the configuration file `server.xml`, as follows:

    <Context path="/ebx" docBase="(...)" crossContext="true"/>

### Data source of the EBX® repository

##### Note

If the EBX® main configuration specifies the property `ebx.persistence.url`, then the environment entry below will be ignored by EBX® runtime. This option is only provided for convenience; it is always recommended to use a fully-configurable datasource. In particular, the size of the connection pool must be set according to the number of concurrent users. See Configuring the EBX® repository for more information on this property.

The JDBC datasource for EBX® is specified in the deployment descriptor `WEB-INF/web.xml` of the '`ebx`' web application as follows:

Reserved resource name | Default JNDI name | Description
--- | --- | ---
`jdbc/EBX_REPOSITORY` | JBoss: `java:/EBX_REPOSITORY` | JDBC data source for EBX® Repository. Java type: `javax.sql.DataSource`

##### See also

- Configuring the EBX® repository
- Rules for the database access and user privileges

### Mail sessions

##### Note

If the EBX® main configuration does not set `ebx.mail.activate` to 'true', or if it specifies the property `ebx.mail.smtp.host`, then the environment entry below will be ignored by EBX® runtime. See SMTP in the EBX® main configuration properties for more information on these properties.

SMTP and email is declared in the deployment descriptor `WEB-INF/web.xml` of the '`ebx`' web application as follows:

Reserved resource name | Default JNDI name | Description
--- | --- | ---
`mail/EBX_MAIL_SESSION` | JBoss: `java:/EBX_MAIL_SESSION` | Java Mail session used to send emails from EBX®. Java type: `jakarta.mail.Session`

### JMS connection factory

##### Note

If the EBX® main configuration does not activate JMS through the property `ebx.jms.activate`, the environment entry below will be ignored by the EBX® runtime. See JMS in the EBX® main configuration properties for more information on this property.

The JMS connection factory is declared in the deployment descriptor `WEB-INF/web.xml` of the '`ebx`' web application as follows:

Reserved resource name | Default JNDI name | Description | Required
--- | --- | --- | ---
`jms/EBX_JMSConnectionFactory` | JBoss: `java:/EBX_JMSConnectionFactory` | JMS connection factory used by EBX® to create connections with the JMS provider configured in the operational environment of the application server. Java type: `jakarta.jms.ConnectionFactory` | Yes

##### Note

For deployment on WildFly, JBoss application servers with JNDI capabilities, you must update `EBX.ear` for additional mappings of all required resource names to JNDI names.

### JMS for data services

To configure data services to use JMS instead of the default HTTP, you must configure the JMS connection factory and the following queues, declared in the `WEB-INF/web.xml` deployment descriptor of the '`ebx`' web application. This is the only method for configuring JMS for data services.

When a SOAP request is received, the SOAP response is optionally returned if the header field `JMSReplyTo` is defined. If so, the fields `JMSCorrelationID` and `JMSType` are retained.

See JMS for more information on the associated EBX® main configuration properties.

##### Note

If the EBX® main configuration does not activate JMS through the property `ebx.jms.activate`, then the environment entries below will be ignored by EBX® runtime. See JMS in the EBX® main configuration properties for more information on this property.

Reserved resource name | Default JNDI name | Description | Required
--- | --- | --- | ---
`jms/EBX_QueueIn` | JBoss: `java:/jms/EBX_QueueIn` | JMS queue for incoming SOAP requests sent to EBX® by other applications. Java type: `jakarta.jms.Queue` | No
`jms/EBX_QueueFailure` | JBoss: `java:/jms/EBX_QueueFailure` | JMS queue for failures. It contains incoming SOAP requests for which an error has occurred. This allows replaying these messages if necessary. Java type: `jakarta.jms.Queue` Note: For this property to be read, the main configuration must also activate the queue for failures through the property `ebx.jms.activate.queueFailure`. See JMS in the EBX® main configuration properties for more information on these properties. | No

### JAR files scanner

To speed up the web applications server startup, the JAR files scanner configuration should be modified to exclude, at least, the `ebx.jar` and `ebx-addons.jar` libraries.

For example, on Tomcat, this should be performed in the `tomcat.util.scan.StandardJarScanFilter.jarsToSkip` property from the `catalina.properties` file.

## Installation notes

EBX® can be deployed on any Jakarta EE 9 or greater application server that supports Servlet 5.0 and above. The following documentation on deployment and installation notes are available:

- Installation note for Tomcat 10.1.X

- Installation note for JBoss EAP 8.0.X

- Installation note for WebSphere Application Server Liberty 23.X

##### Attention

- The EBX® installation notes on Jakarta EE 9 application servers do not replace the native documentation for each application server.

- These 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.

- In these examples, no additional EBX® modules are deployed. To deploy custom or add-on modules, the best practice is to rebuild an EAR with the module as a web application at the same level as the other EBX® modules. The web application must declare its class path dependency as specified by the Java™ 2 Platform Enterprise Edition Specification, v1.4:

  > J2EE.8.2 Optional Package Support

  > (...)

  > A JAR format file (such as a JAR file, WAR file, or RAR file) can reference a JAR file by naming the referenced JAR file in a Class-Path header in the Manifest file of the referencing JAR file. The referenced JAR file is named using a URL relative to the URL of the referencing JAR file. The Manifest file is named META-INF/MANIFEST.MF in the JAR file. The Class-Path entry in the Manifest file is of the form:

  > `Class-Path: list-of-jar-files-separated-by-spaces`

  In an "industrialized" process, it is strongly recommended to develop a script that automatically builds the EAR, with the custom EBX® modules, the EBX® web applications, as well as all the required shared libraries.

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

Documentation > Administration Guide > Installation & configuration