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

# Installation note for Tomcat 10.1.X

## Overview

##### Attention

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

- 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 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 `$CATALINA_HOME` to refer to the Tomcat installation directory, and from which most relative paths are resolved. However, if the `$CATALINA_BASE` directory has been set for a multiple instances configuration, it should be used for each of these references.

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

## Requirements

- Java SE 17 LTS

- Apache Tomcat 10.1.X

- Database and JDBC driver

- EBX® CD

##### See also

- Supported environments

## Tomcat Application Server installation

1. Download Tomcat 10.1.X core binary distribution from:

   https://tomcat.apache.org/download-10.cgi ,

2. Run the installer or extract the archive and perform a standard installation with default options.

## EBX® home directory configuration

1. Create EBX_HOME directory, for example `C:\EBX\home`, or `/home/ebx`,

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

   `C:\EBX\home\ebx.properties`, or `/home/ebx/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.

## Tomcat Application Server and Java Virtual Machine configuration

1. Modify `$CATALINA_HOME/conf/server.xml` (or `$CATALINA_BASE/conf/server.xml`) file.

   Add these attributes `encodedSolidusHandling="passthrough"` and `allowBackslash="true"` to the `Connector` element.

   Add the following line to the `<Host>` element:

   `<Context path="/ebx" crossContext="true" docBase="ebx.war"/>`

   In our example, we will have:

   `<Host name=...>`

   `... ...`

   `<Context path="/ebx" crossContext="true" docBase="ebx.war"/>`

   `... ...`

   `</Host>`

2. Modify the `$CATALINA_HOME/conf/catalina.properties` (or `$CATALINA_BASE/conf/catalina.properties`) file by adding the following lines to the `tomcat.util.scan.DefaultJarScanner.jarsToSkip` property:

   `ebx.jar,\`

   `ebx-addons.jar,\`

   `ebx-lz4.jar,\`

3. Configure the Java Virtual Machine properties,

   - For Windows' Command Prompt launch;

     Set the environment variables by creating a `setenv.bat` file either into `$CATALINA_HOME\bin` or `$CATALINA_BASE\bin`. This file will hold, at least, the following lines:

         set EBX_HOME=<path_to_the_directory_ebx_home>
         set EBX_OPTS=-Debx.home="%EBX_HOME%" -Debx.properties="%EBX_HOME%\ebx.properties"
         set JAVA_OPTS=%EBX_OPTS% %JAVA_OPTS%
         set CLASSPATH=<$CATALINA_HOME_or_$CATALINA_BASE>\compress\ebx-lz4.jar;%CLASSPATH%

     Where <$CATALINA_HOME_or_$CATALINA_BASE> must be replaced by `%CATALINA_HOME%` or `%CATALINA_BASE%` if they have been configured. Otherwise this piece of text must be replaced by the Tomcat installation directory's path.

   - For Windows users that have installed Tomcat as a service;

     Set Java options through the Tomcat service manager GUI (Java tab).

     Be sure to set options on separate lines in the Java Options field of the GUI:

         -Debx.home="<path_to_the_directory_ebx_home>"
         -Debx.properties="<path_to_the_directory_ebx_home>\ebx.properties"

     Update the service using the //US// parameter to set the proper classpath value.

         C:\> tomcat10 //US//Tomcat10 --Classpath="<$CATALINA_HOME_or_$CATALINA_BASE>\compress\ebx-lz4.jar;%CLASSPATH%"

     Where <$CATALINA_HOME_or_$CATALINA_BASE> must be replaced by `%CATALINA_HOME%` or `%CATALINA_BASE%` if they have been configured. Otherwise this piece of text must be replaced by the Tomcat installation directory's path.

   - For Unix shell launch;

     Set the environment variables by creating a `setenv.sh` file either into `$CATALINA_HOME/bin` or `$CATALINA_BASE/bin`. This file will hold, at least, the following lines:

         EBX_HOME="<path_to_the_directory_ebx_home>"
         EBX_OPTS="-Debx.home=${EBX_HOME} -Debx.properties=${EBX_HOME}/ebx.properties"
         export JAVA_OPTS="${EBX_OPTS} ${JAVA_OPTS}"
         export CLASSPATH="<$CATALINA_HOME_or_$CATALINA_BASE>/compress/ebx-lz4.jar:${CLASSPATH}"

     Where <$CATALINA_HOME_or_$CATALINA_BASE> must be replaced by `${CATALINA_HOME}` or `${CATALINA_BASE}` if they have been configured. Otherwise this piece of text must be replaced by the Tomcat installation directory's path.

   Caution: Accounts used to launch EBX® must have create/update/delete rights on EBX_HOME directory.

   ##### Note

   <path_to_the_directory_ebx_home> is the directory where we copied `ebx.properties`. In our example, it is `C:\EBX\home`, or `/home/ebx`.

   ##### Note

   For a Data compression library native installation, ensure to only reference it in the CLASSPATH environment variable.

## EBX® and third-party libraries deployment

1. Copy third-party libraries from the EBX® CD to `$CATALINA_HOME/lib/` (or `$CATALINA_BASE/lib/`) directory, except for the Data compression library. In our example, we will have:

   `$CATALINA_HOME/lib/jakarta.mail-2.0.1.jar` coming from `ebx.software/lib/lib-mail` directory.

   `$CATALINA_HOME/lib/h2-2.2.224.jar` (default persistence factory) coming from `ebx.software/lib/lib-h2` directory.

   The exact description of these components is given in chapter Software components. Obviously, if those components are already deployed on the class-loading system, they do not have to be duplicated.

2. Create a directory dedicated to the Data compression library (for example `$CATALINA_HOME/compress` or `$CATALINA_BASE/compress`) and copy it there.

   ##### Note

   Ensure that the library is copied in the directory pointed out by the previously updated CLASSPATH environment variable.

3. Copy from EBX® CD the `ebx.software/lib/ebx.jar` file to `$CATALINA_HOME/lib/` (or `$CATALINA_BASE/lib/`) directory. In our example, we will have:

   `$CATALINA_HOME/lib/ebx.jar`

## EBX® web applications deployment

1. Copy from the EBX® CD the war files in `ebx.software/webapps/wars-packaging` to the `$CATALINA_HOME/webapps/` (or `$CATALINA_BASE/webapps/`) directory. In our example, we will have:

   `$CATALINA_HOME/webapps/ebx.war`: Initialization servlet for EBX® applications,

   `$CATALINA_HOME/webapps/ebx-authentication.war`: Central authentication application,

   `$CATALINA_HOME/webapps/ebx-dataservices.war`: Data Services web application,

   `$CATALINA_HOME/webapps/ebx-dma.war`: Data Model Assistant web application,

   `$CATALINA_HOME/webapps/ebx-hub.war`: Hub web application,

   `$CATALINA_HOME/webapps/ebx-manager.war`: Master Data Management web application,

   `$CATALINA_HOME/webapps/ebx-root-1.0.war`: Provides a common default module for data models,

   `$CATALINA_HOME/webapps/ebx-ui.war`: User Interface web application,

   `$CATALINA_HOME/webapps/ebx-ide.war`: Integrated Development Environment web application,

## EBX® application start

1. After Tomcat launch, run EBX® web application by entering the following URL in the browser: http://localhost:8080/ebx/

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

Documentation > Administration Guide > Installation & configuration > Installation notes