How To Complete a Single Instance Cantara Installation on Tomcat - Linux

Required components

The following components are required to complete this installation. It is assumed that you have a patch Windows 2016 Server instance available with sufficient privileges to install and configure the required components.

Deploying the Cantara JDE Objects to Your JD Edwards Server

To deploy the Cantara JDE objects

In this example installation, only the minimum required components will be deployed. To utilise Rinami Cantara mobile applications you will be required to install additional JD Edwards components from the Cantara Portal. Please refer to your implementation partner as to which components should be deployed. The same method can be utilised for each module.

It is assumed that the person completing the Cantara JD Edwards Components installation has experience working within the JD Edwards Object Management Workbench and is familiar with the process of defining, building and deploying JD Edwards packages.

The steps required to deploy the Cantara JD Edwards Components to your Oracle JD Edwards EnterpriseOne system are:

1. Create an OMW project and promote it so that new objects can be created within the project. The project can be named as per your corporate naming standard. If there is no preferred standard then the project can be named as per the PAR file, so for example, the core components projects would be named CNTR_CORE. The most common configuration would be to promote the project to status 21 and create the objects within the DV environment.
2. Within OMW, select the new project and click the Restore action.
   

   

3. Select Yes to use a ZIP file and then choose the Cantara JD Edwards Components file from your download location. An example of the file name would be PRJ_CNTR_CORE_E920_5.0.5.par
4. Ensure that all of the objects within the project are checked in.
5. Complete a Full package build and deployment to any enterprise servers that will be connected to Cantara for each environment required.
6. Once the package is deployed, go back into OMW and generate the tables included in the project
7. You can promote and deploy the objects to each required path code using the normal JD Edwards OMW and deployment server process.

A Full build is required

Cantara is an Oracle Validated Integration and uses the system code Q35. As the base components introduce a new code library within Oracle JD Edwards EnterpriseOne a full build is required to initialise this library. Subsequent updates and enhancements may be deployed via an update package in certain circumstances. Due to the way that Oracle JD Edwards caches method signatures, it is generally recommended a full package build is deployed with each update to the Cantara components.

Refer to the JD Edwards Objects and Configuration topic for more details.

Configuring the JD Edwards Enterprise Server

To ensure the correct operation of the Cantara Integration Platform you must ensure that all relevant kernels and components on the target Oracle JD Edwards EnterpriseOne Enterprise servers are configured correctly. This should be completed using Server Manager but can also be done via direct edit of the JDE.INI if that is standard policy. Updates to the Enterprise servers should only be completed by an experienced JD Edwards System Administrator that understands Configurable Network Computing (CNC) activities.

Specific configuration elements to be reviewed/updated are:

List Retrieval Engine

The Output Location is where temporary query results are written prior to being returned the Cantara via the XMLList engine. You should check that this path is correct, the defined folder exists and that the user that the JD Edwards server kernels are running as have read and write permissions to it. It is recommended that this folder be monitored and any expired query results that have not been automatically removed are deleted. 

The Repository Size is the percentage of free disk space that the list engine will allocate to temporary results. If this limit is exceeded then the list engine will fail to return results to the Cantara. It is important to ensure that the location selected output location has sufficient free disk space to handle both the maximum size of expected queries but also takes into account the likely number of concurrent queries being executed by users. This setting only takes effect if disk monitoring is enabled.

Use Disk Monitor enables disk monitoring. It is recommended that this enabled to ensure that query activities to do not directly impact the operation of the JD Edwards enterprise server.

XML Lookup

Generally the XML List settings do not need to be updated from the default except for the last setting which is XML Kernel Reply 7. This must be set to 1 (enabled) to ensure that UBE submission through Cantara operates correctly.

Kernel Definitions

There are a number of kernels required to enable integration to JD Edwards. Changes kernel definitions can significantly impact the performance and operation of the JD Edwards Enterprise server and therefore should be only made after consideration for all of the factors involved.

The Call Object Kernel is central to the operation of the enterprise servers. Generally this will not require changes however if you are expecting a high number of concurrent users to be accessing JD Edwards through the Cantara platform then it may be necessary to increase the maximum number of kernels allowed to support the increased load.

The XML List Kernel will process query requests from Cantara. These kernels are not multi-threaded and are shared by concurrent users and therefore sufficient resources should be provided to prevent queuing of query requests.

The XML Service Kernel is responsible for receiving and routing service requests from Cantara. If you experience timeouts of execution of functions then it may be that there are insufficient XML Service kernels available to process the volume of requests.

Further details of the elements to be modified are available at JD Edwards Objects and Configuration under JDE.INI settings.

These changes must be done to each JD Edwards Enterprise or Batch server that will be integrated to via Cantara. To apply any changes made to the enterprise server configuration, the relevant services will need to be restarted.

Creating the required installation folders

This is an example configuration for a full local install of the Cantara Integration Platform with all components installed under a single parent directory of /app/Cantara. Please refer to your internal guidelines with regards to installation paths and folders and adjust as necessary.

The following folders should be created:

Install Oracle Java SE JDK 1.8.0

There are range of options for installing the Java JDK on linux platforms, in this instance we will be installing from the tarball (see Required Components) using the command line.

Navigate to the JDK path created above, and download or move the tarball to this directory, then enter:

tar zxvf jdk-8u201-linux-x64.tar.gz

Once this is done the tarball can be deleted as desired.

The only required component is the Development Tools. These are to be installed in /app/Cantara/Java/jdk1.8.0.

Install and Configure Oracle MySQL Server

Refer to the MySQL installation documentation for linux here:

https://dev.mysql.com/doc/refman/8.0/en/linux-installation-yum-repo.html

Database Creation

As we will be installing two farms you will need to define at least two databases as the data for each farm is defined at database level. You can optionally install a database per component and per farm which is the configuration described below. The benefit of separating the databases is that you can then relocate each component to different database servers (eg production and non-production) as required. The following databases will be created:

The SQL script to create a Cantara database user and the above databases would be:

CREATE USER 'cantara'@'localhost' IDENTIFIED BY 'PASSWORD';

CREATE SCHEMA `cntr_access_test` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_access_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_assur_test` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_assur_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
CREATE SCHEMA `cntr_admin_prod` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;

GRANT ALL ON `cntr_access_test`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_access_prod`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_assur_test`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_assur_prod`.* TO 'cantara'@'localhost';
GRANT ALL ON `cntr_admin_prod`.* TO 'cantara'@'localhost';

Once the database schemas have been created you can then run the appropriate installation script again each as required.

Install and Configure MongoDB Server (Optional)

This is an optional component which can be deployed to provide detailed audit and transaction history from the Cantara Administration Console

Please refer to the MongoDB installation instructions for CentOS (or other versions of linux) here:

https://docs.mongodb.com/manual/tutorial/install-mongodb-on-red-hat/

Install Apache Tomcat 9.0 servers

This documentation provides an example installation of Apache Tomcat 9.0 on a Centos 7 Server system. Please refer to the Apache Tomcat documentation relevant to your operating environment for further details and options with regards to the installation and configuration of the Apache Tomcat server.

Create a Tomcat User

For security purposes, Tomcat should not have privileged (i.e. root) access so a user and group should be created to run the services.

First create a tomcat group:

$ sudo groupadd tomcat

Next create a tomcat user:

$ sudo useradd -s /bin/false -g tomcat -d /opt/tomcat tomcat

Now that the user has been created, install the Tomcat services.

Tomcat installation

As we are running both a production and test farm on the same machine, we will require two instances of Apache Tomcat to be installed.

Extract the Apache Tomcat archive to /app/Cantara/Test/apache-tomcat-9.0 and to /app/Cantara/Prod/apache-tomcat-9.0.

Once extracted, update permissions to allow the tomcat user to access them:

$ sudo chown -R tomcat:tomcat /app/Cantara/Test/apache-tomcat-9.0


$ sudo chown -R tomcat:tomcat /app/Cantara/Prod/apache-tomcat-9.0

As two instances of Tomcat will be running, one must be reconfigured to use different ports. The following changes should be made to /app/Cantara/Test/apache-tomcat-9.0/conf/server.xml:

<Server port="8005" shutdown="SHUTDOWN">
changed to
<Server port="8105" shutdown="SHUTDOWN">


<Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
changed to
<Connector port="8180" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8543" />


<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
changed to
<Connector port="8109" protocol="AJP/1.3" redirectPort="8443" />

Create systemd Service Files

To run the services you will need to create two service files. In the example they will be cntrtest.service and cntrprod.service. Copy the following into each and edit as needed.

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment=JAVA_HOME=/app/Cantara/Java/jdk.1.8.0/jre
Environment=CATALINA_PID=/app/Cantara/Prod/apache-tomcat-9.0/temp/tomcat.pid
Environment=CATALINA_HOME=/app/Cantara/Prod/apache-tomcat-9.0
Environment=CATALINA_BASE=/app/Cantara/Prod/apache-tomcat-9.0
Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dcantara.console.etc=/app/Cantara/console/etc -Dcantara.assur.etc=/app/Cantara/Prod/Assur/etc -Dcantara.worker.etc=/app/Cantara/Prod/Worker/etc'

ExecStart=/app/Cantara/Prod/apache-tomcat-9.0/bin/startup.sh
ExecStop=/app/Cantara/Prod/apache-tomcat-9.0/bin/shutdown.sh

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment=JAVA_HOME=/app/Cantara/Java/jdk.1.8.0/jre
Environment=CATALINA_PID=/app/Cantara/Test/apache-tomcat-9.0/temp/tomcat.pid
Environment=CATALINA_HOME=/app/Cantara/Test/apache-tomcat-9.0
Environment=CATALINA_BASE=/app/Cantara/Test/apache-tomcat-9.0
Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom -Dcantara.assur.etc=/app/Cantara/Test/Assur/etc -Dcantara.worker.etc=/app/Cantara/Test/Worker/etc'

ExecStart=/app/Cantara/Test/apache-tomcat-9.0/bin/startup.sh
ExecStop=/app/Cantara/Test/apache-tomcat-9.0/bin/shutdown.sh

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

Once these files have been created, ensure they are placed in /etc/systemd/system and enter the following command:

$ sudo systemctl daemon-reload

If your Cantara system will be accessible from outside of the network is it recommended that the default Apache Tomcat applications are removed. To do this go to the %CATALINA_HOME\webapps folder and remove all of the sub-folders. This will mean that all configuration/deployment will need to be done through file edits.

Extract the MySQL Java Connector archive and copy the jdbc driver JAR into the %CATALINA_HOME/lib folder. The file will be named mysql-connector-java-8.0.11.jar. Also copy the javax.mail.jar file into the same Apache Tomcat library folder.

Once each of the web applications have been deployed you can complete the configuration of the Apache Tomcat instances.

Before starting these services, the Cantara web application packages will need to be deployed.

Deploy the Cantara Assur Servers

To deploy the Test Farm Cantara Assur Server

1. Extract the Assur application archive file into the folder /app/Cantara/Test/Assur/assur.war. 

2. Copy the context.xml from within the /app/Cantara/Test/Assur/assur.war/META-INF folder into the /app/Cantara/Test/apache-tomcat-9.0/conf/Catalina/localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be assur.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the test Assur instance.

   assur.xml

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="/app/Cantara/Test/Assur/assur.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/TestAssur"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_assur_test"
               username="cantara"/>
   </Context>

To deploy the Prod Farm Cantara Assur Server

1. Extract the Assur application archive file into the folder /app/Cantara/Prod/Assur/assur.war. 

2. Copy the context.xml from within the /app/Cantara/Prod/Assur/assur.war/META-INF folder into the /app/Cantara/Prod/apache-tomcat-9.0/conf/Catalina/localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be assur.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the production Assur instance.

   assur.xml

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase=" /app/Cantara/Prod/Assur/assur.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/ProdAssur"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_assur_prod"
               username="cantara"/>
   </Context>

Deploying the Cantara Access Servers

To deploy the Test Farm Cantara Access Server

1. Extract the Access application archive file into the folder /app/Cantara/Test/Worker/worker.war. 

2. Copy the context.xml from within the /app/Cantara/Test/Worker/worker.war/META-INF folder into the /app/Cantara/Test/apache-tomcat-9.0/conf/Catalina/localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be cantara.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the test Access instance.

   cantara.xml

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="/app/Cantara/Test/Worker/worker.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/TestWorker"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_access_test"
               username="cantara"/>
       <Resource auth="Container"
               mail.debug="false" 
               mail.smtp.auth="false" 
               mail.smtp.host="smtp.rinami.com"
               mail.transport.protocol="smtp" 
               name="mail/Rinami"
               global="mail/Rinami"
               type="javax.mail.Session"/>
   </Context>

   You can optionally include a definition for an SMTP mail server. This will enable the Cantara Integration Platform to send email messages either via REST service calls or as part of the Advanced Job Scheduler functionality.

4. Copy the required Oracle JD Edwards Connector library files into the folder /app/Cantara/Test/Worker/worker.war/WEB-INF/lib

5. Extract the contents of the AIS_Client_Java_API archive and copy the AIS_Client_2.0.jar file into the folder /app/Cantara/Test/Worker/worker.war/WEB-INF/lib.

   

   AIS Version

   If your tools release is older than 9.2.2.0 then you should use the AIS_Client.jar file. If you do not wish to deploy AIS support then you do not need the client jar.

To deploy the Prod Farm Cantara Access Server

1. Extract the Access application archive file into the folder /app/Cantara/Prod/Worker/worker.war 

2. Copy the context.xml from within the /app/Cantara/Prod/Worker/worker.war/META-INF folder into the /app/Cantara/Prod/apache-tomcat-9.0/conf/Catalina/localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be cantara.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the production Access instance.

   cantara.xml

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="/app/Cantara/Prod/Worker/worker.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/ProdWorker"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_access_prod"
               username="cantara"/>
       <Resource auth="Container"
               mail.debug="false" 
               mail.smtp.auth="false" 
               mail.smtp.host="smtp.rinami.com"
               mail.transport.protocol="smtp" 
               name="mail/Rinami"
               global="mail/Rinami"
               type="javax.mail.Session"/>
   </Context>

   You can optionally include a definition for an SMTP mail server. This will enable the Cantara Integration Platform to send email messages either via REST service calls or as part of the Advanced Job Scheduler functionality.

4. Copy the required Oracle JD Edwards Connector library files into the folder /app/Cantara/Prod/Worker/worker.war/WEB-INF/lib

5. Extract the contents of the AIS_Client_Java_API archive and copy the AIS_Client_2.0.jar file into the folder /app/Cantara/Prod/Worker/worker.war/WEB-INF/lib.

   

   AIS Version

   If your tools release is older than 9.2.2.0 then you should use the AIS_Client.jar file. If you do not wish to deploy AIS support then you do not need the client jar.

Deploying the Cantara Administration Console

To deploy the Cantara Administration Console Server

1. Extract the Console application archive file into the folder /app/Cantara/Console/console.war. 

2. Copy the context.xml from within the  /app/Cantara/Console/console.war/META-INF folder into the /app/Cantara/Prod/apache-tomcat-9.0/conf/Catalina/localhost folder. The file should be renamed to match the context that will be used for the deploy. By default this would be console.xml.

3. The context file includes the context name to be used for the deployment and example connection settings for database and email JNDI definitions. Update the file to match web archive installation path and the database created for the production Assur instance.

   console.xml

   XML

   <?xml version="1.0" encoding="UTF-8"?>
   <Context docBase="/app/Cantara/Console/console.war">
       <Manager pathname="" />
       <Resources cachingAllowed="true" cacheMaxSize="100000" />
       <Resource
               auth="Container"
               driverClassName="com.mysql.jdbc.Driver" 
               maxTotal="100"
               maxIdle="30" 
               maxWaitMillis="10000"
               name="jdbc/Console"
               password="PASSWORD"
               type="javax.sql.DataSource" 
               url="jdbc:mysql://localhost:3306/cntr_admin_prod"
               username="cantara"/>
   </Context>
   
   
   

Start the Services and Verify Service Installation

Now that the Tomcat services had .wars have been deployed, start the services with the following commands:

$ sudo systemctl start cntrprod


$ sudo systemctl start cntrtest

The services should start cleanly and logs should be clear of errors. Check the following log files for errors:

1. /app/Cantara/Prod/apache-tomcat-9.0/logs/catalina.yyyy-mm-dd.log
2. /app/Cantara/Test/apache-tomcat-9.0/logs/catalina.yyyy-mm-dd.log

Verify Landing Pages and Update Server Tokens

To control administration access between components, credentials must be set on each of the access server and assur server components. This is accessed through the Change Server Token link in the top right of each component landing page. The default credentials are admin/admin.

Configuring the Cantara Administration Console

When you launch the Cantara Administration Console you will be greeted with a login prompt. The default username and password are admin/admin.

Initial configuration must be completed in the following order.

Base Administration Console Configuration

Go to the Administration page and set your Tenant ID and Database JNDI name. Your tenant ID is available from the Cantara Portal at https://portal.cantara.cloud. 

Define the Test Farm

Go to the Farm page and enter the first farm details.

Define the Assur Instance

Configure the Assur Instance details.

Define the Test Farm Worker Instance

Define the Production Farm

Go to the Farm page and then to the Farms tab to add a new Farm. Follow the same process as the test farm but ensuring the URL endpoints and JNDI entries are correct for Production.

Enter your Enterprise Licence information

You can access your licence information from the Cantara Portal at https://portal.cantara.cloud