Important: It is strongly discouraged to run other applications on the JBoss Enterprise Application Platform (EAP) with LSPS since LSPS is using a customized Hibernate.

To set up JBoss EAP 6.4.0 with LSPS, do the following:

Install JBoss EAP.
Create JBoss module with the LSPS login module:
1. Copy lsps-security-jboss-${lsps.version}.jar to $EAP_HOME/modules/com/whitestein/lsps/security/main.
2. Create the file $EAP_HOME/modules/com/whitestein/lsps/security/main/module.xml with the following content:
```
<module xmlns="urn:jboss:module:1.0" name="com.whitestein.lsps.security">
  <resources>
    <resource-root path="lsps-security-jboss-${lsps.version}.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="org.picketbox" />
  </dependencies>
</module>
```
  Take a note of the module name since it is used later for security realm configuration.

Create a JBoss module with your JDBC driver. Type IV JDBC drivers are recommended.

For MySQL you need to copy MySQL Connector/J, that is, mysql-connector-java-<VERSION>.jar to $EAP_HOME/modules/com/mysql/main. Then create $EAP_HOME/modules/com/mysql/main/module.xml with following content:

<module xmlns="urn:jboss:module:1.0" name="com.mysql">
  <resources>
    <resource-root path="mysql-connector-java-<VERSION>-bin.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

For Microsoft SQL server, get the Microsoft SQL driver sqljdbc4.jar and copy it to $EAP_HOME/modules/com/microsoft/sqlserver/main.

Also consider adding the sendStringParametersAsUnicode=false property.

<module xmlns="urn:jboss:module:1.0" name="com.microsoft.sqlserver">
  <resources>
    <resource-root path="sqljdbc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

For Oracle 11g, copy ojdbc6.jar to $EAP_HOME/modules/com/oracle/jdbc/main

  <module xmlns="urn:jboss:module:1.0" name="com.oracle.jdbc">
    <resources>
      <resource-root path="ojdbc6.jar"/>
    </resources>
    <dependencies>
      <module name="javax.api"/>
      <module name="javax.transaction.api"/>
    </dependencies>
  </module>

The module name will be used later for creating data source.

Configure JMS in the server profile file (typically, $EAP_HOME/standalone/configuration/standalone-full.xml):

Set JMS to be persistent with <persistence-enabled>true</persistence-enabled>.

<subsystem xmlns="urn:jboss:domain:messaging:3.0">
   <hornetq-server>
      <persistence-enabled>true</persistence-enabled>
      <journal-file-size>102400</journal-file-size>
 
      <connectors>
        <http-connector name="http-connector" socket-binding="http">
           <param key="http-upgrade-endpoint" value="http-acceptor"/>
       </http-connector>

Add queue and topic under jms-destinations:

<jms-queue name="LSPS_QUEUE">
  <entry name="java:jboss/jms/LSPS_QUEUE"/>
</jms-queue>
<jms-topic name="LSPS_TOPIC">
  <entry name="java:jboss/jms/LSPS_TOPIC"/>
</jms-topic>

LSPS will use the default JMS connection factory.

Configure your data source in the server profile file (typically, $EAP_HOME/standalone/configuration/standalone-full.xml).

The data source must be an XA-datasource with the transaction isolation TRANSACTION_READ_COMMITTED and the JNDI name must be jdbc/LSPS_DS.

For MySql, add the following under the data sources subsystem:

<xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="false">
  <driver>mysqlxa</driver>
  <xa-datasource-property name="URL">jdbc:mysql://localhost:3306/lsps?useUnicode=true&amp;characterEncoding=utf-8</xa-datasource-property>
  <security>
    <user-name>lsps</user-name>
    <password>lsps</password>
  </security>
  <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
  <xa-pool>
    <min-pool-size>10</min-pool-size>
    <max-pool-size>20</max-pool-size>
    <prefill>true</prefill>
  </xa-pool>
</xa-datasource>

For Microsoft SQL server, add the following under the data sources subsystem:

  <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="true">
    <driver>mssqlxa</driver>
    <xa-datasource-property name="URL">jdbc:sqlserver://localhost;databaseName=lsps</xa-datasource-property>
    <security>
      <user-name>lsps</user-name>
      <password>lsps</password>
    </security>
    <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
    <xa-pool>
      <min-pool-size>10</min-pool-size>
      <max-pool-size>20</max-pool-size>
      <prefill>true</prefill>
    </xa-pool>
    <new-connection-sql>select 1</new-connection-sql>
    <validation>
      <check-valid-connection-sql>select 1</check-valid-connection-sql>
    </validation>
  </xa-datasource>

For for Oracle 11g XE server, add the following under data sources subsystem:

  <xa-datasource jndi-name="java:/jdbc/LSPS_DS" pool-name="LSPS_DS" enabled="true" use-java-context="true">
    <driver>oraclexa</driver>
    <xa-datasource-property name="URL">jdbc:oracle:thin:@localhost:1521:XE</xa-datasource-property>
    <security>
      <user-name>lsps</user-name>
      <password>lsps</password>
    </security>
    <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
    <xa-pool>
      <min-pool-size>10</min-pool-size>
      <max-pool-size>20</max-pool-size>
      <prefill>true</prefill>
    </xa-pool>
    <validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker"/>
      <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"/>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter"/>
    </validation>
  </xa-datasource>

In the <drivers> element, make sure to delete the h2 driver (driver with the name="h2" attribute) and add <driver> referred to from the datasource definition:

for MySql (make sure the driver is 5.5 compatible):

  <driver name="mysqlxa" module="com.mysql">
    <!-- for version 8: -->
    <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class>
  </driver>

for MSSql:

  <driver name="mssqlxa" module="com.microsoft.sqlserver">
    <xa-datasource-class>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xa-datasource-class>
  </driver>

for Oracle:

  <driver name="oraclexa" module="com.oracle.jdbc">
    <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
  </driver>

Delete driver with name="h2".

Set Infinispan acquire-timeout setting to at least 5 minutes in your profile XML, such as standalone-full.xml. For details refer to the respective faq entry

   <local-cache name="passivation">
        <locking isolation="REPEATABLE_READ" acquire-timeout="600000"/>
        <transaction mode="BATCH"/>
        <file-store passivation="true" purge="false"/>
   </local-cache>
</cache-container>

Consider adding logging.properties for better log legibility:
# Specify the handlers to create in the root logger
# (all loggers are children of the root logger)
# The following creates two handlers
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler
# Set the default logging level for the root logger
.level = WARN
# Set the default logging level for new ConsoleHandler instances
java.util.logging.ConsoleHandler.level = ALL
# Set the default logging level for new FileHandler instances
java.util.logging.FileHandler.level = ALL
# Set the default formatter for new ConsoleHandler instances
java.util.logging.ConsoleHandler.formatter = com.whitestein.lsps.log.LSPSFormatter
# Set the default formatter for new FileHandler instances
java.util.logging.FileHandler.formatter = com.whitestein.lsps.log.LSPSFormatter
# Set the logging level for the LSPS
com.whitestein.lsps.level = FINER
Create a mail session with the JNDI name mail/LSPS_MAIL defined in $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss config under the mail subsystem tag.
```
<mail-session name="lspsmail" jndi-name="java:jboss/mail/LSPS_MAIL">
  <smtp-server outbound-socket-binding-ref="mail-smtp"/>
</mail-session>
```
Important: If you are using Microsoft Exchange Server as your mail server, make sure you have enabled the smtp feature.
Set up the login module for the LSPS realm: add the following to the "security-domains" of the security subsystem tag in $EAP_HOME/standalone/configuration/standalone-full.xml or the respective JBoss config referencing the security module from step 2:
```
<security-domain name="lspsRealm" cache-type="default">
  <authentication>
    <login-module code="com.whitestein.lsps.security.jboss.LSPSRealm" flag="required" module="com.whitestein.lsps.security">
    <module-option name="dsJndiName" value="/jdbc/LSPS_DS"/>
    </login-module>
  </authentication>
</security-domain>
```
The attribute cache-type of the security-domain element turns on caching of user login data. As a side effect, changes to user credentials will not be used until after the cache is flushed; for example, if a user changes user's password through the web console but the user is already using Designer, they will be able to connect Designer to the server with the old credentials. You can turn the cache off by omitting the cache-type attribute of the security-domain element. The security domain definition will look as follows:
```
<security-domain name="lspsRealm">
  <authentication>
    <login-module code="com.whitestein.lsps.security.jboss.LSPSRealm" flag="required" module="com.whitestein.lsps.security">
    <module-option name="dsJndiName" value="/jdbc/LSPS_DS"/>
    </login-module>
  </authentication>
</security-domain>
```
For additional module options, refer to the JavaDoc of the implementing class and super classes. You can also plug in your own authentication module.
Configure networking (optional).

By default JBoss binds to the local host. You can change the configuration in $EAP_HOME/standalone/configuration/standalone-full.xml (or the JBoss config you use). For example, to bind JBoss to any IPv4 address use the following setting:
```
<interface name="management">
  <any-address/>
</interface>
<interface name="public">
  <any-address/>
</interface>
<interface name="unsecure">
  <any-address/>
</interface>
```
Set up the JBoss option file in $EAP_HOME/bin/standalone.conf (or the JBoss config you use).
1. Set up Java memory options:
  - minimum setting: JAVA_OPTS="-Xms128m -Xmx512m -XX:MaxPermSize=128m .....
  - recommended setting: JAVA_OPTS="-Xms256m -Xmx1024m -XX:MaxPermSize=256m .....
  JVM might require larger amount of memory depending on the uploaded and used LSPS modules.
2. Set up the server startup configuration file to use (pointing to the configuration file you modified), e.g. for standalone-full.xml:
```
JAVA_OPTS="$JAVA_OPTS -Djboss.server.default.config=standalone-full.xml"
```
3. Add the following Java system properties to the config file, so it is added to the Java options passed to the JVM:
  1. Configure EMF framework to work properly on JBoss:
```
JAVA_OPTS="$JAVA_OPTS -Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl"
```
  2. Configure the conversion of empty numeric inputs:
```
JAVA_OPTS="-Dorg.apache.el.parser.COERCE_TO_ZERO=false $JAVA_OPTS"
```
    LSPS needs the system property org.apache.el.parser.COERCE_TO_ZERO to be set to "false" (see https://jsp-spec-public.dev.java.net/issues/show_bug.cgi?id=183). Without the property, empty input in numeric fields in the web application is interpreted as 0. This interpretation causes some functionalities not to work.
Copy the LSPS Application EAR to $JB_HOME/standalone/deployments.