JBoss Enterprise Application Platform 7.4

This topic describes how LumisXP should be installed on the server JBoss Enterprise Application Platform 7.4.

It is assumed in this documentation that the portal installation is located in a path that from this point on is simply referred to as $LUMIS_HOME. It is also assumed that the JBoss installation is located in $JBOSS_HOME.

Module Installation and Upgrade

At $LUMIS_HOME/lib/jboss7/modules there are modules that need to be installed in JBoss. It consists of a Lumis Shared module (lumis/shared), JDBC driver modules (lumis/jdbc).

To install these modules, you must copy the directory $LUMIS_HOME/lib/jboss7/modules to $JBOSS_HOME/modules. During an upgrade, you must first delete the old directory of these modules (lumis/shared and lumis/jdbc in $JBOSS_HOME/modules) and then install them.

Profile Configuration

The profile configuration will be according to the architecture chosen for the solution. Normally, it will be in one of the files standalone.xml, domain.xml, or host.xml (for more information, consult the JBoss documentation).

In the configuration, you must include the system properties below. To do this, include the properties as shown in the example below. If the system-properties element does not exist, add it after </extensions>.

<system-properties> <property name="org.xml.sax.driver" value="com.sun.org.apache.xerces.internal.parsers.SAXParser"/> <property name="javax.xml.parsers.SAXParserFactory" value="com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl"/> <property name="javax.xml.parsers.DocumentBuilderFactory" value="com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl"/> <property name="javax.xml.transform.TransformerFactory" value="com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"/> </system-properties>

In the configuration, you must include the Lumis module in the subsystem jboss:domain:ee. To do this, simply create a global module node as follows:

<subsystem xmlns="urn:jboss:domain:ee:1.2"> <global-modules> <module name="lumis.shared" slot="main"></module> </global-modules> </subsystem>

It is also necessary to increase the deployment timeout so that the portal deployment can be completed. To do this, simply include (or change accordingly) the deployment-timeout attribute of the deployment-scanner node in the jboss:domain:deployment-scanner subsystem. This time is measured in seconds and should be adjusted to the characteristics of the environment.

It is also necessary to include a security-domain in the subsystem jboss:domain:security. To do this, simply add a new node as follows:

<security-domain name="LumisPortal" cache-type="default"> <authentication> <login-module code="lumis.portal.authentication.LumisLoginModule" flag="sufficient"></login-module> </authentication> </security-domain>

Memory Configuration

The memory configurations of JBoss are defined in standalone.conf/standalone.conf.bat or domain.conf/domain.conf.bat, depending on the mode in which JBoss will be executed. By default, it includes the configuration -XX:MaxMetaspaceSize=256m which may be low for LumisXP, and it is recommended to increase it to 512m. This is sufficient for most simple portals, but all memory configurations should be reviewed according to the needs of each solution or environment.

Deploy the Portal

• In standalone mode:

  Copy the folder $LUMIS_HOME/www to the deployment folder of the standalone configuration in JBoss ($JBOSS_HOME/standalone/deployments). The copied folder should be renamed to <context name>.war (for example: portal.war , if the context is portal ). A blank file with the same name as the folder with the extension .dodeploy should also be created (following the example, it would be portal.war.dodeploy ).

• In domain mode:

  Generate a web application file ("WAR") from the folder $LUMIS_HOME/www and install the WAR via the application server's administrative console.

Creating and Configuring the datasource

This item describes how to configure LumisXP to use a datasource on JBoss. These steps are only necessary if you wish to use a datasource.

For the proper use of datasource in the portal, the JDBC driver module corresponding to the database used must be installed on the application server, as well as the Lumis Shared module. The source location of the module will be:

• for Oracle: $LUMIS_HOME/lib/jboss7/modules/lumis/jdbc/driver/oracle;
• for SQL Server: $LUMIS_HOME/lib/jboss7/modules/lumis/jdbc/driver/sqlserver;
• for MySQL: $LUMIS_HOME/lib/jboss7/modules/lumis/jdbc/driver/mysql

The corresponding module must be copied to $JBOSS_HOME/modules (for example, if the database used is Oracle, the folder structure should be $JBOSS_HOME/modules/lumis/jdbc/driver/oracle/main).

The module must also be referenced in the configuration file, as in the case of the Lumis Shared module. To do this, simply insert its reference in the global modules, as highlighted below:

<subsystem xmlns="urn:jboss:domain:ee:1.0"> <global-modules> <module name="lumis.shared" slot="main"></module> <module name="lumis.jdbc.driver.oracle" slot="main"></module> </global-modules> </subsystem>

After doing this, the datasource can be created in the jboss:domain:datasources subsystem, as shown in the following example:

<subsystem xmlns="urn:jboss:domain:datasources:1.0"> <datasources> <datasource jndi-name="java:jboss/datasources/PortalDS" pool-name="PortalDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url> jdbc:oracle:thin:@localhost:1521:ora11g </connection-url> <driver> ojdbc8 </driver> <security> <user-name>USER</user-name> <password>PASSWORD</password> </security> </datasource> <drivers> <driver name="ojdbc8" module="lumis.jdbc.driver.oracle"> <driver-class> oracle.jdbc.driver.OracleDriver </driver-class> </driver> </drivers> </datasources> </subsystem>

Within the datasources node, two nodes must be created. One driver node, inside the drivers node, to define the driver to be used and one datasource node for creating the datasource itself.

In the driver node, it is important to define:

• The driver name: which will be the name that the datasource will reference as driver (in the example, the name used is ojdbc14);
• The module that contains the driver: which module has this driver (lumis.jdbc.driver.<database type>, in the example it is lumis.jdbc.driver.oracle);
• Driver class:
  • for Oracle: oracle.jdbc.driver.OracleDriver;
  • for SQL Server: net.sourceforge.jtds.jdbc.Driver;
  • for MySQL: com.mysql.cj.jdbc.Driver

In the datasource node, define:

• JNDI Name: it is the name to be referenced in the lumishibernate.cfg.xml;
• Connection URL: the URL used for the connection;
• Driver: the name of the driver used (use the same name defined in the driver node);
• User and Password: login credentials for the database.

Extra step for MySQL users:

The downloaded MySQL driver described in the MySQL topic should be copied to the folder $JBOSS_HOME/modules/lumis/jdbc/driver/mysql/main and the module.xml file (residing in the same directory) should be adjusted according to the following example (example for the driver mysql-connector-java-8.0.11.jar, the name must be adjusted according to the driver file that will be used):

<?xml version="1.0" encoding="UTF-8"?> <!-- $Revision: 18096 $ $Date: 2015-12-10 14:20:20 -0200 (qui, 10 dez 2015) $ --> <module xmlns="urn:jboss:module:1.0" name="lumis.jdbc.driver.mysql"> <resources> <resource-root path="mysql-connector-java-8.0.11.jar" ></resource> </resources> <dependencies> <module name="javax.api"></module> </dependencies> </module>

If desired, the password of the datasource can remain encrypted. To do this, it must be generated by executing the following command in the $JBOSS_HOME directory:

java -cp modules\org\picketbox\main\picketbox-4.0.1.jar;modules\org\jboss\logging\main\jboss-logging-3.0.1.GA.jar org.picketbox.datasource.security.SecureIdentityLoginModule [PASSWORD]

It is also necessary to include a security-domain in the subsystem jboss:domain:security to store the datasource user and the encrypted password. To do this, just add a new node as follows:

<security-domain name="portal-ds" cache-type="default"> <authentication> <login-module code="SecureIdentity" flag="required"> <module-option name="username" value="USER"></module-option> <module-option name="password" value="[ENCRYPTED PASSWORD]"></module-option> </login-module> </authentication> </security-domain>

In this security domain, you must define: username (in the example, USER), encrypted password (in the example, [ENCRYPTED PASSWORD]) and name of the security domain (in the example, portal-ds).

After that, you must change the security node of the datasource by removing the user-name and password nodes and adding a new security-domain node referencing the previously created security domain, as follows:

<subsystem xmlns="urn:jboss:domain:datasources:1.0"> <datasources> <datasource jndi-name="java:jboss/datasources/PortalDS" pool-name="PortalDS" enabled="true" jta="true" use-java-context="true" use-ccm="true"> <connection-url> jdbc:oracle:thin:@localhost:1521:ora11g </connection-url> <driver> ojdbc8 </driver> <security> <security-domain> portal-ds </security-domain> </security> </datasource> <drivers> <driver name="ojdbc8" module="lumis.jdbc.driver.oracle"> <driver-class> oracle.jdbc.driver.OracleDriver </driver-class> </driver> </drivers> </datasources> </subsystem>

For more information on datasource configuration, see https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/7.0/paged/configuration-guide/chapter-13-datasource-management.

JVM Parameter Configuration

For the proper functioning of LumisXP, the following parameters must be added to the JVM of JBoss EAP:

• --add-opens=java.base/java.lang=ALL-UNNAMED
• --add-opens=java.base/java.io=ALL-UNNAMED

For more information on how to add parameters to the JVM of JBoss EAP, see the your documentation .