Documentation Home
Changelog

Tomcat

Installation

Download and unzip Tomcat (http://tomcat.apache.org/download-85.cgi). We recommend using the latest version of Tomcat which at time of writing is the latest 8.5 patch version.

Known Incompatibilities

7.0.63 and below

Adding an extra startup argument for javaagent:/path/to/spring-instrument.jar is required in order for the Broadleaf class transformers to execute. All other versions of Tomcat enable this by default so this JVM parameter is not required.

7.0.70 through 7.0.78, 8.0.0 through 8.0.32

If you are using Broadleaf 5.2 with a Spring Boot project, it does not include a web.xml. This is required for these versions of Tomcat in order for class transformation to work correctly. Without a web.xml you will get the following startup error:

java.lang.IllegalStateException: The classes
[org.broadleafcommerce.common.config.domain.AbstractModuleConfiguration, org.broadleafcommerce.common.sitemap.domain.SiteMapGeneratorConfigurationImpl, org.broadleafcommerce.core.catalog.domain.CategoryImpl, org.broadleafcommerce.core.catalog.domain.ProductImpl, org.broadleafcommerce.core.order.domain.DiscreteOrderItemImpl, org.broadleafcommerce.core.order.domain.FulfillmentOptionImpl, org.broadleafcommerce.core.order.fulfillment.domain.FulfillmentBandImpl, org.broadleafcommerce.core.order.domain.OrderItemImpl, org.broadleafcommerce.core.search.domain.FieldImpl, com.broadleafcommerce.accountcredit.profile.core.domain.CreditAccountImpl, com.broadleafcommerce.enterprise.workflow.domain.change.MapStructureImpl, com.broadleafcommerce.enterprise.workflow.domain.change.PersistencePerspectiveItemImpl]
are managed classes within the MergePersistenceUnitManager
but were not detected as being transformed by the EntityMarkerClassTransformer. There can be multiple causes for this:
1. Session persistence is enabled in your servlet container (like Tomcat) and an entity object has been loaded by the container before being loaded by the application's classloader. Ensure that session persistence is disabled; in Tomcat ensure that a <Manager pathname="" /> element exists in your context.xml.
2. You are inadvertently using class scanning to find a ServletContainerInitializer class, triggering a class load of all classes before transformers have been registered. If you are using a web.xml, ensure that there is an <absolute-ordering /> element somewhere in that file.
3. The classes are being used as apart of an @Bean method or in some other runtime capacity that is initialized prior to persistence manager startup

This is caused by Tomcat scanning the classpath looking for a ServletContextInitializer. Follow the instructions in Using a web.xml to force the use of a web.xml in your project and disable Tomcat's classpath scanning.

Setup Your Project for Tomcat

Follow the instructions on Deploying a .war File. Once these changes are made you can build your project using Maven and there will be now be a .war file in your target directory. This is the file that Tomcat needs to deploy your project.

Setup Tomcat Context

You will need to disable session persistence in tomcat in order to deploy broadleaf. You can do this by adding an empty manager entry to the context.xml file in the tomcat/conf directory. Example:

 <Manager pathname="" />

Configure SSL for Tomcat

Using the provided keystore

In your deployable projects (site, admin, api) you will find a src/main/resources/blc-example.keystore. Move this to somewhere the Tomcat can read and use broadleaf for the keyStorePass and keyPass parameters of the SSL connector: 

<Connector SSLEnabled="true" clientAuth="false" keystoreFile="[/path/to/blc-example.keystore]" keystorePass="broadleaf" keyPass="broadleaf" maxThreads="150" port="8443" protocol="HTTP/1.1" scheme="https" secure="true" sslProtocol="TLS"/>

Creating your own keystore

A program called keytool is included with your JDK, and you can use it to easily create a keystore. Here is an example showing how to create a keystore:

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore [/preferred/keystore/path]

Keytool will ask you to enter the password you want to use for the keystore, choose whatever you like (but don't forget it). Keytool will also ask you some other questions, and after that it will create a keystore file at the path specified or in your home directory if you did not specify a path.

Next you will need to configure tomcat to use the keystore that you just created. You can do this by adding a new connector entry to the server.xml file in the tomcat/conf directory. Here is an example, be sure to use the correct path to your keystore and the password you used for the keystore:

<Connector SSLEnabled="true" clientAuth="false" keystoreFile="[/preferred/keystore/path]" keystorePass="[password]" maxThreads="150" port="8443" protocol="HTTP/1.1" scheme="https" secure="true" sslProtocol="TLS"/>

Tomcat Deploy

Now that tomcat is configured correctly you can deploy your .war file. The easiest way to do this is to first delete everything that is currently in the tomcat/webapps directory. Next copy the .war file from the site/target directory to the tomcat/webapps. Now you need to create a setenv.sh file for Unix systems or setenv.bat file for Windows in the tomcat/bin directory and to set the CATALINA_OPTS variable with any JVM startup parameters. This sets the memory usage to 1.5GB and initiates a debug port on port 8000

Unix bin/setenv.sh

export CATALINA_OPTS="-Xmx1536M -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

Windows bin/setenv.bat

set "CATALINA_OPTS=-Xmx1536M -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"
exit /b 0

Finally, you can start tomcat by executing the bin/startup.sh on Unix or bin/startup.bat.

When you deployed the site war the default name of the file that you copied is ROOT.war. This tells tomcat to deploy that file at the root context (localhost:8080/). For the admin, you can copy the built admin.war file from the target directory to the tomcat webapps to cause tomcat to deploy the admin to the /admin context (localhost:8080/admin).

For more information about deploying to tomcat see https://tomcat.apache.org/tomcat-8.0-doc/html-manager-howto.html.