Deploy Semarchy xDM to Apache Tomcat

This page explains how to configure and deploy Semarchy xDM to an Apache Tomcat application server.

On this page, <tomcat> refers to the Apache Tomcat installation folder.

For more details about the deployment and configuration processes for Apache Tomcat, see the official Tomcat documentation.

Install additional libraries

The installation file includes additional libraries that 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.

  • Required libraries that are missing from the Java Development Kit (JDK) must be added manually. For more information, see Additional libraries.

  • Tomcat does not include JSON libraries (javax.json or jakarta.json), which are required for Semarchy xDM and must be added manually. For more information, see Additional libraries.

  • 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 (on Windows) or <tomcat>/bin/shutdown.sh (on UNIX/Linux). Similarly, after installing the libraries, restart the Apache Tomcat server using <tomcat>/bin/startup.bat (on Windows) or <tomcat>/bin/startup.sh (on UNIX/Linux)

JDBC drivers

Install the Java Database Connectivity (JDBC) drivers to connect the repository and data location databases, as well as the additional drivers required for the databases that are 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 JavaMail session resources in Java EE.

To install the JavaMail libraries, copy the temp/mdm-server/additional-libraries/com.sun.mail.jakarta.mail_<version>.jar file to the <tomcat>/lib/ folder.

Additional libraries

All libraries required for Semarchy that are not provided in your version of the JDK must be copied to the <tomcat>/lib/ folder.

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

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

org.glassfish.jakarta.json_*.jar
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 logging

It is recommended to change the default configuration of the Tomcat server logging to benefit from the built-in startup logging feature 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 (on UNIX/Linux) or <tomcat>/bin/setenv.bat (on 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.

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

After this initial configuration, you can fine-tune the logging configuration for the platform.

Configuration file

The Semarchy xDM application deployed in a Tomcat server is configured using a semarchy.xml file that can be modified and must be provided as part of the application deployment process.

This file is only used to configure a JavaMail session and 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, 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. Any modification automatically triggers 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 a JavaMail session

This configuration is required for mail notifications using JavaMail session resources in JEE.

To configure a 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.
    For a description of the properties, see the SMTP package documentation.

<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" -->

<!-- Adjust the default settings below to specify timeout durations.
 For an SMTP server:
    mail.smtp.connectiontimeout = 30000
    mail.smtp.timeout = 30000
    mail.smtp.writetimeout = 30000
 For an SMTPS server:
    mail.smtps.connectiontimeout = 30000
    mail.smtps.timeout = 30000
    mail.smtps.writetimeout = 30000 -->
Gmail users may have to allow access to "less secure apps" if facing connection issues.

Configure a JMS destination

Semarchy xDM can use a Java Message Service (JMS) 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.

Some 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 Java Naming and Directory Interface (JNDI) lookup factory to request JNDI connections and resources (queues or topics).

This component is available as a JAR file named com.semarchy.tool.jee.tomcat_<xdm_version>.<build-date>-<git_commit>.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
     (e.g., 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
     (e.g., 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 The type of JMS destination, which can be a queue or a 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.

Use JMS destinations

When configuring the notification server and job notification policy, or ordering 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 environment variable is set to be able to authenticate and create the repository.

To deploy the application:

  1. Upload the semarchy.war file and the semarchy.xml configuration file to a temporary directory on the Tomcat server machine (e.g., /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 (e.g., /semarchy).
      This context defines the URL to the deployed application: http://<application_server_host>:<application_server_port>/<context>/.

    • In the XML Configuration file URL, enter the path to the configuration file in the Tomcat server (e.g., /temp/semarchy.xml).

    • In the WAR or Directory URL, enter the path to the WAR file in the Tomcat server (e.g., /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 method. For more information about active and passive nodes, see Configure Semarchy xDM for high availability.

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.