Deploy Semarchy xDM to Apache Tomcat

This document explains how to configure and deploy the Semarchy xDM Server with Apache Tomcat.

In this document, <tomcat> refers to the Apache Tomcat installation folder.

Refer to the Tomcat Documentation for more details about the deployment and configuration processes for Apache Tomcat.

Install Additional Libraries

The installation file includes additional libraries which are not part of the Semarchy xDM code but which are required by the application server where Semarchy is running :

  • All installations need a database driver to connect to the repository and data locations.

  • Java 11 (JDK 11) does not include certain libraries which are included in Java 8 (JDK 8), so these files must be added manually.

  • Tomcat does not include json libraries (javax.json or jakarta.json), required for Semarchy xDM. This library must be added manually.

  • Customers who wish to send email notifications need an additional jar file.

Before adding libraries, you must stop the Apache Tomcat server using <tomcat>/bin/shutdown.bat (Windows) or <tomcat>/bin/shutdown.sh (UNIX/Linux).
Similarly, after installing the libraries, restart the Apache Tomcat server using <tomcat>/bin/startup.bat (Windows) or <tomcat>/bin/startup.sh (UNIX/Linux)

JDBC Drivers

Install the JDBC drivers to connect the repository and data location databases, as well as the additional drivers required for the databases accessed by the xDM Dashboard charts and dashboards, or profiled by xDM Discovery.

To install the JDBC drivers:

  1. Copy the appropriate database driver file from temp/mdm-server/additional-libraries/ to the <tomcat>/lib directory.

  2. Copy additional drivers to the same directory.

Mail Session Libraries

This configuration is required for mail notifications using JEE Mail Session.

To install the Java Mail Libraries:

  1. Copy the temp/mdm-server/additional-libraries/com.sun.mail.jakarta.mail_<version>.jar file to the <tomcat>/lib/ folder

Additional libraries

If running Tomcat with a JDK 11, you must copy to the <tomcat>/lib/ folder libraries required for Semarchy that are not provided in this version of the JDK. This step is not required for a JDK 8.

You must also add the org.glassfish.jakarta.json library for all Tomcat deployments.

You will find these libraries, listed below, in the temp/mdm-server/additional-libraries/ folder.

# Libraries for all Tomcat deployments
org.glassfish.jakarta.json_*.jar

# Libraries for Tomcat on JDK 11
com.sun.activation.jakarta.activation_*.jar
com.sun.istack.commons-runtime_*.jar
com.sun.xml.fastinfoset.FastInfoset_*.jar
jakarta.jws-api_*.jar
jakarta.xml.bind-api_*.jar
jakarta.xml.soap-api_*.jar
org.apache.servicemix.specs.jaxws-api-*.jar
org.glassfish.jaxb.runtime_*.jar
org.glassfish.jaxb.txw2_*.jar
org.jvnet.staxex.stax-ex_*.jar

Configure the Logging

It is recommended to change the default configuration of the Tomcat server logging to benefit from the built-in startup logging provided by Semarchy xDM.

To configure the startup logging:

  1. Copy to the <tomcat>/conf/ folder the log4j2.semarchy.xml file available in the mdm-server/samples folder of the xDM - Server Installation package.
    This file configures the startup logging to raise only meaningful messages.

  2. Update Tomcat startup properties:

    1. Open the <tomcat>/bin/setenv.sh (UNIX/Linux) or <tomcat>/bin/setenv.bat (Windows) file with a text editor.

    2. Add the following to the CATALINA_OPTS variable:

      -Dorg.ops4j.pax.logging.property.file=$CATALINA_BASE/conf/log4j2.semarchy.xml

    3. Save the file.

With this configuration, when Semarchy xDM starts, it logs startup messages to the <tomcat>/logs/semarchy.log file in addition to the console.

After this initial configuration, you can finely Configure the Logging for the platform.

Configuration File

The Semarchy xDM application deployed in a Tomcat server is configured using a semarchy.xml that you modify and provide as part of the application deployment process.

This file is only used to configure JavaMail session and the JMS destinations.
Other elements are configured either in the startup configuration (Repository connections and secrets management) or in the platform itself (datasources and identity providers (SSO), users and roles).

The configuration file used after deployment by a running application is located in the <tomcat>/conf/Catalina/localhost/ folder. Such a file may be directly modified on the server machine. This triggers automatically an application restart with the updated configuration. Note that if you un-deploy the application, this file is deleted and lost.

It is recommended to always keep a backup copy of the latest configuration file. You will need it in the event of a re-deployment, or when upgrading the Semarchy xDM application.

Configure JavaMail Session

This configuration is required for mail notifications using JEE Mail Session.

To configure JavaMail Session:

  1. Edit the semarchy.xml file.

  2. In the <context> configuration element add the entry given below and then save the semarchy.xml file. Change the entry below to match your SMTP server configuration. See the SMTP package documentation for a description of the properties.

<Resource name="mail/Session" auth="Container" type="javax.mail.Session"
 mail.smtp.host="<mail_server_host>"
 mail.port="<mail_server_port>"
 mail.smtp.user="<mail_user_name>"
 mail.transport.protocol="smtp"
 password="<mail_user_password>"
 mail.smtp.auth="true" />
 <!-- Add the following to the configuration in case of a SASL Authenticator error:
 mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
 mail.smtp.socketFactory.port="<mail_server_port>"
 mail.smtp.socketFactory.fallback="false"
 -->
Gmail Users may have to allow access to "Less Secure Apps" if facing connection issues.

Configure a JMS Destination

Semarchy xDM can use a JMS (Java Message Service) provider as a notification server, to send job completion notifications to other applications in the form of JMS messages.

In most cases, the resource definition is generic and follows the Tomcat generic guidelines.

Certain JMS servers do not precisely follow the JMS Standards and require specific mechanisms and configuration to connect and access their JMS destinations. For these cases, Semarchy xDM includes a generic JNDI lookup factory to request a JNDI Connections and Resources (Queue or Topic).

This component is available as a jar named com.semarchy.tool.jee.tomcat-<tomcat_version>.jar in your Semarchy xDM installation package.

JMS with the JNDI Lookup Factory

To configure the JNDI Lookup Factory:

  1. Copy the temp/mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-<tomcat_version>.jar file to the $TOMCAT_HOME/lib directory.

  2. Copy the client libraries (.jar files) required for your JMS Server to the $TOMCAT_HOME/lib directory.

  3. Edit the semarchy.xml file and add the following resource declarations:

Example 1. Connection Factory resource definition
<!-- The Connection Factory encapsulates a set of connection configuration parameters.
     It is used to create a connection with the JMS provider. -->

<Resource name="jms/<connection_factory_name>"          (1)
    auth="Container"
    type="javax.jms.ConnectionFactory"
    factory="com.semarchy.tool.jee.tomcat.jndi.JndiLookupFactory"
    jndiKey="<connection_factory_jndi_location_in_provider>"(2)
    initialCtxFactory="<initial_context_factory>"       (3)
    providerUrl="<provider_url>"                (4)
    username = "<jms_server_login>"             (5)
    password = "<jms_server_password>"          (5)
/>
<!-- Depending on the JMS provider, you must provide additional parameters.
     For example:
     java.naming.security.protocol = "ssl"
-->

The Connection Factory resource definition uses the following parameters:

1 The Tomcat resource name for your JMS connection factory.
2 The location of the connection factory JNDI resource in the remote JNDI provider.
3 The initial context factory class, specific to the JNDI provider.
4 The URL of the JNDI provider.
5 The login and password required to access the JNDI resource, if required.
Example 2. JMS Destination resource definition
<!-- A destination is a JMS Queue or Topic to send notifications to. -->

<Resource name="jms/<destination_name>"             (1)
    auth="Container"
    type="javax.jms.Queue"                  (2)
    factory="com.semarchy.tool.jee.tomcat.jndi.JndiLookupFactory"
    jndiKey="<destination_jndi_location_in_provider>"   (3)
    initialCtxFactory="<initial_context_factory>"       (4)
    providerUrl="<provider_url>"                (5)
    username = "<jms_server_login>"             (6)
    password = "<jms_server_password>"          (6)
/>
<!-- Depending on the JMS provider, you must provide additional parameters.
     For example:
     java.naming.security.protocol = "ssl"
-->

The JMS destination resource definition uses the following parameters:

1 The resource name of your JMS destination in Tomcat.
2 Type of the JMS destination. Can be a Queue or Topic.
3 The location of the JMS destination JNDI resource in the remote JNDI provider.
4 The initial context factory class, specific to the JNDI provider.
5 The URL of the JNDI provider.
6 The login and password required to access the JNDI resource, if required.

Using JMS Destinations

When configuring the Notification Server and Job Notification Policy, or order to use the JMS destination defined:

  • Use the jms/<connection_factory_name> value in the notification server Connection Factory URL property.

  • Use the jms/<destination_name> value in the job notification JMS Destination property.

Both those values must be prefixed with java:comp/env/ when used.

Deploy the Application

Startup Checklist

For the Semarchy xDM application to start correctly, make sure that your application server environment is correctly set up.

  • The repository and the data locations database schemas are created.

  • The driver libraries are installed in the application server.

  • The startup configuration is set to connect the repository schema.

  • For an initial startup, the setup token environement variable is set to be able to authenticate and create the repository.

To deploy the application:

  1. Upload the semarchy.war war file and the semarchy.xml configuration file to a temporary directory on the Tomcat server machine, for example /temp/.

  2. Connect to the Apache Tomcat Manager (http://<tomcat_host>:<tomcat_port>/manager/).

  3. In the Deploy directory or WAR file located on the server section:

    • Enter the Context Path for this deployment. This context defines the URL to the deployed application: http://<application_server_host>:<application_server_port>/<context>/.
      Use for example /semarchy for the context.

    • In the XML Configuration file URL, enter the path to the configuration file in the Tomcat server, for example: /temp/semarchy.xml

    • In the WAR or Directory URL, enter the path to the war file in the Tomcat server, for example: /temp/semarchy.war

  4. Click the Deploy button.

The Semarchy xDM application is deployed in the server.

Deploying Passive Nodes
The above process describes the deployment of an active node of Semarchy xDM. The process for deploying a passive node in a high-availability/load-balancing setup is similar. For passive nodes, semarchy-passive.war should be deployed renamed to semarchy.war and deployed using the same.
See Configure Semarchy xDM for High-Availability for more information about active and passive nodes.

Test the Application

To test the application:

  1. Open a web browser.

  2. In the URL, enter: http://<tomcat_host>:<tomcat_port>/<context>/.

The Semarchy xDM Login page appears.