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
orjakarta.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:
-
Copy the appropriate database driver file from
temp/mdm-server/additional-libraries/
to the<tomcat>/lib
directory. -
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:
-
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:
-
Copy to the
<tomcat>/conf/
folder thelog4j2.semarchy.xml
file available in themdm-server/samples
folder of the xDM - Server Installation package.
This file configures the startup logging to raise only meaningful messages. -
Update Tomcat startup properties:
-
Open the
<tomcat>/bin/setenv.sh
(UNIX/Linux) or<tomcat>/bin/setenv.bat
(Windows) file with a text editor. -
Add the following to the
CATALINA_OPTS
variable:-Dorg.ops4j.pax.logging.property.file=$CATALINA_BASE/conf/log4j2.semarchy.xml
-
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:
-
Edit the
semarchy.xml
file. -
In the
<context>
configuration element add the entry given below and then save thesemarchy.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:
-
Copy the
temp/mdm-server/additional-libraries/com.semarchy.tool.jee.tomcat-<tomcat_version>.jar
file to the$TOMCAT_HOME/lib
directory. -
Copy the client libraries (.jar files) required for your JMS Server to the
$TOMCAT_HOME/lib
directory. -
Edit the
semarchy.xml
file 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:
-
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.
|
To deploy the application:
-
Upload the
semarchy.war
war file and thesemarchy.xml
configuration file to a temporary directory on the Tomcat server machine, for example/temp/
. -
Connect to the Apache Tomcat Manager (
http://<tomcat_host>:<tomcat_port>/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:
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
-
-
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. |