Our reference architecture specifies Tomcat as our default container. However, developers may wish to launch Broadleaf Commerce in JBoss for any number of reasons. This tutorial provides the steps necessary to use JBoss AS 7 as the container in which to launch an instance of Broadleaf Commerce version 3.1.x. Note, JBoss AS 7 compatibility for Broadleaf Commerce requires the latest 3.1.1-SNAPSHOT version (or 3.1.1-GA, when available)


You’re using 3.1.1-SNAPSHOT (or 3.1.1-GA, when available)

You’re using MySql (you can swap out the instructions below with the driver and JDBC information applicable to your RDBMS)

You’re launching JBoss using the standalone configuration

You’re installing the Broadleaf Commerce Heat Clinic demo on JBoss (or a project based on the Heat Clinic demo)

If you’re using JRebel, make sure you’re using version 5.5.1 (or later), as earlier versions cause significant delays during JBoss startup

Configure JBoss

Download and install JBoss AS 7 (

Setup datasources for Broadleaf Commerce.

Edit standalone.xml ([jboss installation]/standalone/configuration/standalone.xml)

Add datasource definitions to the datasources subsystem element (change JDBC connection information as appropriate for your environment)













Setup a database driver

Edit standalone.xml

Add a driver definition to the datasources subsystem element


Install the driver jar file

Create a new directory structure for your driver in your JBoss installation ([jboss installation]/modules/com/mysql/jdbc/main)

Copy your JDBC driver jar into the “main” directory you just created

Create a module.xml file in the “main” directory. Here are its contents:

<!- Insert resources here ->

Configure SSL (allows secure pages during checkout in Heat Clinic)

A mvn install on the Heat Clinic demo will cause a keystore file to be created in [heat clinic installation]/site/target/[module name]/WEB-INF/blc-example.keystore

You can use this sample keystore file to configure SSL for JBoss (or, you can use a keystore from a real certificate)

Copy blc-example.keystore to [jboss installation]/standalone/configuration/blc-example.keystore

Edit standalone.xml

Add a secure connector to the web subsystem element

Configure the Application

It’s best to avoid the JPA scanning done by JBoss. This can be achieved by making sure there are no files named persistence.xml in the codebase.

In older versions of Heat Clinic, there is a filed called persistence.xml in [heat clinic installation]/core/src/main/resources/META-INF/persistence.xml

If it’s not done already, rename this file persistence-core.xml

Change any spring application context elements pointing to this file to persistence-core.xml (see this example)


Here is the list of known files containing this persistence.xml reference

[heat clinic installation]/admin/src/main/webapp/WEB-INF/applicationContext-admin.xml

[heat clinic installation]/site/src/main/webapp/WEB-INF/applicationContext.xml

Remove any unused resource-ref elements in web.xml

In regard to Heat Clinic, if it’s not removed already, delete the resource-ref element from [heat clinic installation]/site/src/main/webapp/WEB-INF/web.xml

Configure the application to exclude some unwanted JBoss modules

Create a file called jboss-deployment-structure.xml at

[heat clinic installation]/site/src/main/webapp/WEB-INF/jboss-deployment-structure.xml

[heat clinic installation]/admin/src/main/webapp/WEB-INF/jboss-deployment-structure.xml

The contents of the file are:

Update the runtime properties to use the correct MySQL dialect.

In [heat clinic installation]/core/src/main/resources/runtime-properties/, you will want to update the three persistence unit dialects to say:




(Optional) Make the site module deploy as ROOT.war (rather than mycompany.war)

This allows you to hit the Heat Clinic home page at http://localhost:8080 (rather than http://localhost:8080/mycompany)

Disable the default JBoss application

Edit standalone.xml

Change the enable-welcome-root param to false

Change site’s generated war file name

Edit [heat clinic installation]/site/pom.xml

Change the finalName element value to ROOT



At this point, you can perform a mvn install on your project and take the generated war files for admin and site and place them in [jboss installation]/standalone/deployments so that the JBoss deployment scanner can pick them up and perform the deployment. You may see the following exception during startup:

WARN [] (MSC service thread 1-1) JBAS011006: Not installing optional component org.springframework.web.context.request.async.StandardServletAsyncWebRequest due to exception: JBAS011054: Could not find default constructor for class org.springframework.web.context.request.async.StandardServletAsyncWebRequest

This warning is innocuous and can be ignored. This will likely be resolved in a future version of the Spring framework.

Jboss side change  in standlone.xml

Add datasource node

Add driver node

Add mysql driver into module

Add file blc-example.keystore

Mysql case sensitive in linux system