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 (
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
Similarly, after installing the libraries, restart the Apache Tomcat server using
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:
Copy the appropriate database driver file from
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:
temp/mdm-server/additional-libraries/com.sun.mail.jakarta.mail_<version>.jarfile to the
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
# 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:
Copy to the
log4j.semarchy.propertiesfile available in the
mdm-server/samplesfolder of the xDM - Server Installation package.
This file configures the startup logging to raise only meaningful messages.
Update Tomcat startup properties:
<tomcat>/bin/setenv.bat(Windows) file with a text editor.
Add the following to the
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.|
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:
<context>configuration element add the entry given below and then save the
semarchy.xmlfile. 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:
temp/mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-<tomcat_version>.jarfile to the
Copy the client libraries (.jar files) required for your JMS Server to the
semarchy.xmlfile and add the following resource declarations:
<!-- 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.|
<!-- 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:
jms/<connection_factory_name>value in the notification server Connection Factory URL property.
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
For the Semarchy xDM application to start correctly, make sure that your application server environment is correctly set up.
To deploy the application:
semarchy.warwar file and the
semarchy.xmlconfiguration file to a temporary directory on the Tomcat server machine, for example
Connect to the Apache Tomcat Manager (
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:
Use for example
/semarchyfor the context.
In the XML Configuration file URL, enter the path to the configuration file in the Tomcat server, for example:
In the WAR or Directory URL, enter the path to the war file in the Tomcat server, for example:
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,
See Configure Semarchy xDM for High-Availability for more information about active and passive nodes.