Installation note for Tomcat 10.1.X

Overview

Requirements

• Java SE 17 LTS

• Apache Tomcat 10.1.X

• Database and JDBC driver

• EBX® CD

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.