Create a Project Distribution - BloomReach Experience - Open Source CMS
06-12-2019

Create a Project Distribution

Introduction

Goal

Package your project as a distribution that is ready to be deployed in a Tomcat installation in an environment.

Background

At the end of a development iteration you need to be able to package your project and deploy it to a test, an acceptance and eventually a production server. If you have set up your project with the Maven archetype, creating a project distribution for Tomcat works out of the box. This page explains how to create such a distribution.

Deployment Diagram

Below is a diagram that depicts the structure of the deployment we are aiming at.

(Legend: blue = brXM out-of-the-box, light grey = third party, red = project-specific, orange = environment-specific)

  • Apache Tomcat container
    Two war files are deployed in the Tomcat container (${catalina.base}/webapps/):
  • Common classloader
    ${catalina.base}/common/lib/ is the location of container-wide artifacts. These will be loaded by Tomcat's common classloader.

  • Shared Classloader
    ${catalina.base}/shared/lib is the location where Tomcat's shared classloader will load artifacts from. This classloader is shared between all deployed web applications and enables communication between them. The CMS and Site webapps communicate with each other through the brXM Services and API jars deployed in the shared classloader. 
    When creating a distribution with development data, the repository-data-development and repository-data-site-development jars are also added to ${catalina.base}/shared/lib.
  • Configuration Directory
    Finally ${catalina.base}/conf is where environment-specific configuration can be put. For example, a development environment will typically use a different database configuration than a production environment and so the project distribution might not deliver the configuration settings specific to the production environment. Those can be configured here.
The distribution directory structure is designed as a generic 'baseline' and works out-of-the-box when unpacking the distribution in a default Tomcat installation.
However, please note that common libraries (in common) and environment-specific configuration (in conf) are typically configured at container level (e.g. see Configure the Application Server (Apache Tomcat on Linux)). When deploying a distribution in such an environment, only the webapps and shared directories (blue in the diagram above) should be unpacked. The deployment instructions reflect this.

Create a Project Distribution

A standard Bloomreach Experience Manager project based the Maven archetype provides two profiles in its root POM file which configure the Maven Assembly Plugin that is used to create a distribution:

  • dist to create a distribution without development data
  • dist-with-development-data to create a distribution with development data

Whether you need a distribution with or without development data depends on your use case. Deploying for the first time in a new ("empty") environment may require a distribution with development data in order to seed some content. Subsequent deployments typically don't need any development data to be bootstrapped, unless specifically required by the project release being deployed.

Create a Project Distribution without Development Data

To create a distribution without development data, run the following commands in the project's root directory:

mvn clean verify
mvn -P dist

A tar.gz distribution file has now been created in the target directory of the main project and contains the following files:

$ tar -tvf target/myproject-1.0.0-distribution.tar.gz 
-rw-r--r--  0 johndoe  staff    3578  5 Dec 10:25 conf/log4j2.xml
-rw-r--r--  0 johndoe  staff     850  5 Dec 10:25 conf/context.xml
-rw-r--r--  0 johndoe  staff 107113716  5 Dec 10:32 webapps/cms.war
-rw-r--r--  0 johndoe  staff  32966258  5 Dec 10:32 webapps/site.war
-rw-r--r--  0 johndoe  staff     16030 27 Nov  2017 common/lib/geronimo-jta_1.1_spec-1.1.1.jar
-rw-r--r--  0 johndoe  staff     69246 27 Nov  2017 common/lib/jcr-2.0.jar
-rw-r--r--  0 johndoe  staff    521157 27 Nov  2017 common/lib/mail-1.4.7.jar
-rw-r--r--  0 johndoe  staff     23241  4 Nov 21:24 shared/lib/log4j-slf4j-impl-2.11.1.jar
-rw-r--r--  0 johndoe  staff     41203 27 Nov  2017 shared/lib/slf4j-api-1.7.25.jar
-rw-r--r--  0 johndoe  staff    264060  4 Nov 21:24 shared/lib/log4j-api-2.11.1.jar
-rw-r--r--  0 johndoe  staff   1607947  4 Nov 21:24 shared/lib/log4j-core-2.11.1.jar
-rw-r--r--  0 johndoe  staff     16515 27 Nov  2017 shared/lib/jcl-over-slf4j-1.7.25.jar
-rw-r--r--  0 johndoe  staff     43241  4 Dec 11:20 shared/lib/hippo-cms7-commons-13.0.0.jar
-rw-r--r--  0 johndoe  staff     56877  4 Dec 11:20 shared/lib/hippo-services-13.0.0.jar
-rw-r--r--  0 johndoe  staff    123828  4 Dec 11:19 shared/lib/hippo-repository-api-13.0.0.jar
-rw-r--r--  0 johndoe  staff     31632  4 Dec 11:19 shared/lib/hippo-repository-builtin-13.0.0.jar
-rw-r--r--  0 johndoe  staff    172798  4 Dec 11:21 shared/lib/hst-api-13.0.0.jar

There are two web applications packaged as war files inside a directory called webapps, a number of libraries in a directory called shared/lib, another set in a directory called common/lib, and some configuration files such as a log4j descriptor and a Tomcat context descriptor in the conf directory. This is the directory layout Tomcat uses to load the different artifacts your project delivers. Simply unpacking this distribution in the root directory of a Tomcat installation will put these artifacts in the correct locations.

Create a Project Distribution with Development Data

To create a distribution with development data, run the following commands in the project's root directory:

mvn clean verify
mvn -P dist-with-development-data

A tar.gz distribution file has now been created in the target directory of the main project and contains the same files as a distribution without development data, with the addition of the following file (assuming project name myproject and project version 1.0.0):

-rw-r--r--  0 johndoe  staff      3335  5 Dec 11:09 shared/lib/myproject-repository-data-development-1.0.0.jar
-rw-r--r--  0 johndoe  staff      1335  5 Dec 11:09 shared/lib/myproject-repository-data-site-development-1.0.0.jar

The deployment diagram then looks as follows:

Customization

Internally the Maven Assembly Plugin is configured by an assembly descriptor. This descriptor is located at src/main/assembly/distribution.xml, and includes a number of assembly component descriptors.

Currently this file looks like this:

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
  <id>distribution</id>
  <formats>
    <format>tar.gz</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <componentDescriptors>
    <componentDescriptor>conf-component.xml</componentDescriptor>
    <componentDescriptor>webapps-component.xml</componentDescriptor>
    <componentDescriptor>common-lib-component.xml</componentDescriptor>
    <componentDescriptor>shared-lib-component.xml</componentDescriptor>
  </componentDescriptors>
</assembly>

If you have custom needs, such as an additional web application or a shared library you want packaged, modify the descriptors to your liking. Most cases should be self-explanatory by looking at the contents of the provided descriptors. For instance, to package an additional shared artifact you would add an <include> element with the groupId:artifactId coordinates of that artifact next to the dependency set defined in the shared-lib-component.xml descriptor. Make sure that it is in fact defined as a provided-scoped dependency in your POM or the assembly plugin won't be able to resolve the artifact.

Another common use case involves having to package a container-wide artifact for deployment to ${catalina.base}/common/lib, so that it will be loaded by Tomcat's common class loader. This is for instance the case with JDBC drivers that you want to configure as a JNDI DataSource in Tomcat. You can achieve this by adding the additional dependency to the common-lib-component.xml descriptor. For example to also packages the MySQL driver, add the following include to the dependency set:

 <include>mysql:mysql-connector-java</include>

Again, your projects primary POM descriptor must define this artifact as a provided dependency.

If you have requirements beyond this, refer to the Maven Assembly Plugin descriptor documentation here.

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?