Configuring JBoss

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.

Naming Conventions

In this document, the following conventions are used to indicate the directories you have selected on your servers during installation:

  • JBoss install directory: <JBOSS_HOME>
  • Appian install directory: <APPIAN_HOME>

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 messaging subsystem):

<subsystem xmlns="urn:jboss:domain:messaging:*">

Required Configurations

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:, and installed in <JBOSS_HOME>.

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.

See Also:

Use the Configure Script to Deploy JBoss Configurations

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.

  1. Run the configure script.
  2. Run the Create or select repository command if you have not already created a repository for your configurations.
  3. Run the Register an environment command to create an environment that corresponds to the machine on which you are configuring this instance of JBoss (e.g., dev, test, prod).
  4. Before deploying, configure the required configurations necessary for Appian to run.
  5. Run the Deploy configurations command and choose to deploy configurations to JBoss. This will copy the JBoss configurations for the selected environment to the designated <JBOSS_HOME> directory.
    • To deploy the Appian configuration files, choose to deploy configurations to Appian next or choose to deploy configurations to both initially.

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.

Optional Configurations

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.

JBoss Management User for Shutdown

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.

Open the shutdown.(bat|sh) file for the applicable environment(s) and modify the call jboss-cli.bat section to resemble the following with <username> and <password> replaced by the username and password you just created for your management user.

    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.

Remove ScriptEngineFactory Entry

  1. Navigate to <JBOSS_HOME>/modules/system/layers/base/sun/jdk/main/service-loader-resources/META-INF/services
  2. Edit the javax.script.ScriptEngineFactory file and remove the com.sun.script.javascript.RhinoScriptEngineFactory entry.

This optional step will prevent the following error message from appearing in the JBoss's logs:

ScriptEngineManager javax.script.ScriptEngineFactory: Provider com.sun.script.javascript.RhinoScriptEngineFactory not found

The error occurs because Java 8 includes a different JavaScript engine library, which is used instead of the Rhino script engine. If this optional step is not followed, the product will continue to operate correctly, but this error message will appear repeatedly in the JBoss logs.

Performance and Other JVM Settings

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.

JAVA_GC_SETTINGS="-Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC"
  • Refer to the documentation regarding garbage collection and performance analysis for your chosen application server if you are using an application server other than JBoss.

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: <JBOSS_HOME>/bin.

If this file does not already exist, rename standalone.custom.(bat|sh).example to 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.

 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:

 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:

 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 on Linux systems. If Appian is being installed on Windows, then these options should be specified in standalone.custom.bat per the following example:

set CUSTOM_JAVA_OPTS=-verbosegc -XX:+PrintGCTimeStamps -XX:+PrintGCDetails -Xloggc:gc.txt

set USER_MEM_ARGS=-Xms2048m -Xmx4096m -XX:+HeapDumpOnOutOfMemoryError

Running JBoss as a Windows Service

See also: Setting up JBoss as a Windows Service

Running Multiple JBoss Instances

There are different ways to configure application server redundancy, including clustering, single server host, and separate server options.

Multiple JBoss Instances on a Single Server

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:

  1. Install the second complete instance of Appian and JBoss on the server.
    • For these instructions, <JBOSS_2_HOME> refers to the second JBoss install.
  2. Start the first instance using the following command:
    • <JBOSS_HOME>/bin/standalone.(bat|sh)
  3. Start the second instance with the following command:
    • <JBOSS_2_HOME>/bin/standalone.(bat|sh) -Djboss.socket.binding.port-offset=100

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 -Djboss.socket.binding.port-offset parameter.

  • It is recommended to use different multiples of 100 for the port offsets.

Multiple JBoss Instances on Multiple Servers

To create additional instances of JBoss on additional host servers, complete the following:

  1. Install a complete instance of Appian and JBoss on the new server.
  2. Verify that <APPIAN_HOME>/ear/suite.ear/conf/appian-topology.xml lists the actual hostname of the existing engine server host in the following element:
    • <server host="myAppianServerHost">
    • If such file does not already exist, rename appian-topology.xml.example to appian-topology.xml.
  3. Copy the following files from <APPIAN_HOME>/ear/suite.ear/conf to the new installation:
    • appian-topology.xml
  4. Copy any custom configuration .xml files to the new directory.
  5. Copy your database configuration files <JBOSS_HOME>/standalone/deployments/appian-ds.xml to the same directory on the new server.
  6. Any subsequent custom property or xml file changes must be maintained on all servers.

Configure Mail on Secondary Application Servers

When adding application servers running Appian you can leave the mail resource adaptor unconfigured on new machines. Only one instance needs to be configured.

See Also: Attach Appian to an Existing Email Server or Install an Email Server