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.
|For more details about the deployment and configuration processes for Apache Tomcat, see the Tomcat documentation.|
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.
Java 11 (JDK 11) does not include certain libraries that are included in Java 8 (JDK 8), so these files must be added manually.
Tomcat does not include JSON libraries (
jakarta.json), which are required for Semarchy xDM and 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
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:
Copy the appropriate database driver file from
Copy additional drivers to the same directory.
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
If running Tomcat with 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 JDK 8.
You must also add the
org.glassfish.jakarta.json library for all Tomcat deployments.
You will find the 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
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
log4j2.semarchy.xmlfile available in the
mdm-server/samplesfolder of the
xDM - Server Installationpackage.
This file configures the startup logging to raise only meaningful messages.
Update Tomcat startup properties:
<tomcat>/bin/setenv.sh(on UNIX/Linux) or
<tomcat>/bin/setenv.bat(on Windows) file with a text editor.
Add the following to the
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 finely configure the logging for the platform.|
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.|
This configuration is required for mail notifications using JavaMail Session resources in JEE.
To configure a JavaMail session:
<context>configuration element, add the entry given below, and then save the
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" -->
|Gmail users may have to allow access to "less secure apps" if facing connection issues.|
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-<tomcat_version>.jar in your Semarchy xDM installation package.
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||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.|
When configuring the notification server and job notification policy, or ordering 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.
For the Semarchy xDM application to start correctly, make sure that your application server environment is correctly set up.
To deploy the application:
semarchy.warfile 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 (for example,
This context defines the URL to the deployed application:
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,