Documentation Home
Changelog

JBoss

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 EAP 7.1 as the container in which to launch an instance of Broadleaf Commerce version 5.2.x. JBoss EAP 7.1 compatibility for Broadleaf Commerce requires at least the latest 5.2.x version of Broadleaf.

WARNING: JBoss is built to be a JEE container and tends to bring in a lot of additional subsystems and dependencies that may or may not conflict with the Broadleaf Spring Boot application. Be diligent about excluding unnecessary subsystems and dependencies if you run into conflicts.

Assumptions:

  1. You're launching JBoss using the standalone configuration
  2. You're installing the Broadleaf Commerce Heat Clinic demo on JBoss (or a project based on the Heat Clinic demo)
  3. You are using Broadleaf's out-of-box HSQLDB and not your production DB (additional steps necessary if not using HSQLDB)

Configure JBoss

  1. Download and install JBoss EAP 7.1 (https://developers.redhat.com/products/eap/download/)

  2. Edit $JBOSS_HOME/bin/standalone.conf to include the following JAVA_OPTS, which you may adjust for your environment:

    JAVA_OPTS="$JAVA_OPTS -javaagent:/path/to/your/spring-instrument.jar"
JAVA_OPTS="$JAVA_OPTS -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"
JAVA_OPTS="$JAVA_OPTS -Xms4096m -Xmx4096m"

Configure the Application

  1. Add a jboss-deployment-structure.xml file to your site and admin at src/main/resources/webapp/WEB-INF/jboss-deployment-structure.xml:

    <?xml version="1.0" encoding="UTF-8"?>  
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">
  <deployment>
    <exclude-subsystems>
      <subsystem name="jaxrs" />  
      <subsystem name="webservices" />
      <subsystem name="jsf"/>
    </exclude-subsystems>  
  </deployment>
</jboss-deployment-structure>

    Note: The JSF subsystem especially is incompatible with Broadleaf and causes numerous class loading issues. This MUST be excluded.

  2. Modify your site and admin POMs to package as a war, e.g. <packaging>war</packaging>.

  3. Ensure your site has a finalName of ROOT.

    <build>
    <finalName>ROOT</finalName>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-dependency-plugin</artifactId>
        </plugin>
        ...
    </plugins>
</build>

  4. Add spring-boot-starter-tomcat as a provided dependency to your site and admin POMs:

    <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
    <scope>provided</scope>
</dependency>

  5. Remove tomcat servlet container factory bean and Connector from your SiteConfig or AdminConfig, if they exist:

    // REMOVE THESE METHODS!
@Bean
public EmbeddedServletContainerFactory tomcatEmbeddedServletContainerFactory(@Value("${http.server.port:8080}") int httpServerPort) {
    TomcatEmbeddedServletContainerFactory tomcat = new TomcatEmbeddedServletContainerFactory();
    tomcat.addAdditionalTomcatConnectors(createStandardConnector(httpServerPort));
    return tomcat;
}

private Connector createStandardConnector(int port) {
    Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
    connector.setPort(port);
    return connector;
}

Deploy to JBoss

  1. Build your WARs using mvn package or mvn install
  2. Copy site/target/ROOT.war and admin/target/admin.war to $JBOSS_HOME/standalone/deployments/
  3. Start up JBoss using $JBOSS_HOME/bin/standalone.sh

Note: This will deploy both apps on the 8443 port by default, there may be additional configuration to deploy them to separate ports; this usually involves separate standalone deployments.

Deploy using Wildfly Maven Plugin

You can also use the Wildfly Maven Plugin for an easier time deploying your WAR.

  1. Add the plugin to your root pom.xml:

    <plugin>
    <groupId>org.wildfly.plugins</groupId>
    <artifactId>wildfly-maven-plugin</artifactId>
    <version>1.2.1.Final</version>
</plugin>

  2. Be sure your standalone JBoss is running already using $JBOSS_HOME/bin/standalone.sh

  3. Navigate to your site or admin and run mvn clean install wildfly:deploy, or mvn wildfly:deploy

Details on the Wildfly Maven Plugin can be found here: http://docs.jboss.org/wildfly/plugins/maven/latest/

JBoss EAP 7.2

An additional configuration is needed for EAP 7.2. On startup JBOSS will throw warning messages about the Load-Time Weaving (LTW) implementation. For this version of JBOSS, the specific LTW implementation will need to be changed to support JBOSS specifically. See Table 11.1 in the Spring Framework Reference for the implementation for your specific Application Server.