The following instructions describe the required and optional configurations for using the JBoss EAP application server with Appian.
See System Requirements for the supported version of JBoss.
In this document, the following conventions are used to indicate the directories you have selected on your servers during installation:
This document also makes several references to JBoss subsystem elements. These are elements defined in
<JBOSS_HOME>/standalone/configuration/standalone.xml that define how the server will operate. A subsystem is defined with the following element, where the
xmlns attribute indicates which subsystem is being defined (in this case the
1 <subsystem xmlns="urn:jboss:domain:messaging:*">
You must configure JBoss as instructed below to prepare it for a deployment of Appian. Additional configurations, such as setting a custom Java security manager policy, are not supported.
This document assumes you have already downloaded the supported version JBoss EAP from their website: jboss.org, and installed in
The core required configurations for JBoss are taken care of by the configure script. The steps required to use the configure script to deploy JBoss configurations are documented in the next section. Additional JBoss configurations and considerations are documented in the remaining sections.
Using the Configure Script is required in order to configure your JBoss installation to run Appian. Following these steps will copy the JBoss configuration files packaged with the configure script to the target JBoss directory.
Create or select repositorycommand if you have not already created a repository for your configurations.
Register an environmentcommand to create an environment that corresponds to the machine on which you are configuring this instance of JBoss (e.g., dev, test, prod).
custom.properties.<your_environment>to set the Appian data source and configure the site URL.
appian-topology.xml.<your_environment>and configure your specific topology. See Appian Topology.
Deploy configurationscommand and choose to deploy configurations to JBoss. This will copy the JBoss configurations for the selected environment to the designated
After following these steps, you can version control the configuration files for the environment that now reside in the repository direction. You can make further changes and re-deploy the files as necessary.
This section details optional configurations that can be made for JBoss. Make these changes in the corresponding configuration files stored in the repository created by the configure script, then version control the changes before deploying.
You can optionally create a management user for the JBoss server. If you do this step you must also modify the
shutdown.(bat|sh) file in the configuration repository.
shutdown.(bat|sh) file for the applicable environment(s) and modify the
call jboss-cli.bat section to resemble the following with
<password> replaced by the username and password you just created for your management user.
1 call jboss-cli.bat --user=<username> --password=<password> --connect command=:shutdown
NOTE: The example here is for the
.bat file. Make the similar changes to the
.sh file for installation on Linux.
javax.script.ScriptEngineFactoryfile and remove the
This optional step will prevent the following error message from appearing in the JBoss's logs:
The recommended JVM settings are already set to the values below in the
standalone.custom.(sh|bat) managed by the configure script. You can skip this step when using the configure script or further customize the performance setting in the configuration repository created by running the configure script.
JVM settings are critical for performance-tuning. We recommend that JVM settings be initially tuned for production deployment through performance testing and tuned further after deployment based on the garbage collector log.
The following settings tune the RMI garbage collection to take place once per hour and instruct the garbage collector to attempt to free permanent generation space by collecting classes that are no longer used.
1 JAVA_GC_SETTINGS="-Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC"
The following optional settings record verbose garbage collection output. They can be used in the first few months of production in order to troubleshoot performance issues that may arise due to garbage collection. In general, recording garbage collection output can have a considerable impact on application performance. The number of active sessions that can be supported depends on JVM heap size and the average memory required for the user sessions on the application servers.
The settings described below should be made to the
standalone.custom.(bat|sh) file located at the following file path:
If this file does not already exist, rename
standalone.custom.(bat|sh) before proceeding.
Enable the options below to log garbage collection output. The heap memory settings (size of old and young generation, survivor ratio, and tenuring threshold) are highly relevant to tuning application server performance. The settings listed here also include garbage collection performance tuning settings that have been proven effective in our tests. Set any additional
CUSTOM_JAVA_OPTS required by integrated third-party libraries in this variable as well.
1 CUSTOM_JAVA_OPTS="-verbosegc -XX:+PrintGCTimeStamps -XX:+PrintGCDetails -Xloggc:gc.txt"
Once you've identified the appropriate memory settings, you can override the default memory settings by setting the
USER_MEM_ARGS variable as desired. Configure the variable as follows, changing the memory values to your desired minimum and maximum memory settings:
1 USER_MEM_ARGS="-Xms2048m -Xmx4096m"
Note: The values listed above are the recommended memory values as included in the
standalone.conf(.bat) included in the configure script and represent the minimum required memory settings for most environments. Update these values in
standalone.custom.(bat|sh) as needed.
Appian also recommends instructing the JVM to dump its heap to file if it runs out of memory. This allows for root cause analysis. Configure the variables as follows:
1 USER_MEM_ARGS="-Xms2048m -Xmx4096m -XX:+HeapDumpOnOutOfMemoryError"
The heap dump setting is already configured in the
standalone.conf file provided in the configure script. You do not need to set the property again unless you want to change the default memory settings, which match the examples given here.
NOTE: The examples given above should be placed specifically in
standalone.custom.sh on Linux systems. If Appian is being installed on Windows, then these options should be specified in
standalone.custom.bat per the following example:
1 2 3 set CUSTOM_JAVA_OPTS=-verbosegc -XX:+PrintGCTimeStamps -XX:+PrintGCDetails -Xloggc:gc.txt set USER_MEM_ARGS=-Xms2048m -Xmx4096m -XX:+HeapDumpOnOutOfMemoryError
See also: Setting up JBoss as a Windows Service
There are different ways to configure application server redundancy, including clustering, single server host, and separate server options.
To run Appian on two instances of JBoss running on the same server, you need two installs of JBoss and two installs of Appian. This is due to the file based tracking that JBoss uses when deploying an application.
To configure this setup, complete the following:
<JBOSS_2_HOME>refers to the second JBoss install.
Every additional instance of JBoss on the same machine will require its own version of Appian and its own version of JBoss.
Each must also be run with the
To create additional instances of JBoss on additional host servers, complete the following:
<APPIAN_HOME>/ear/suite.ear/conf/appian-topology.xmllists the actual hostname of the existing engine server host in the following element:
<APPIAN_HOME>/ear/suite.ear/confto the new installation:
.xmlfiles to the new directory.
<JBOSS_HOME>/standalone/deployments/appian-ds.xmlto the same directory on the new server.
When adding application servers running Appian you can leave the mail resource adaptor unconfigured on new machines. Only one instance needs to be configured.