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 Hippo 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 = Hippo 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/):
  • Hippo CMS
    cms.war contains both the CMS authoring application and the content repository, as well as the repository-data-application and repository-data-webfiles modules packaged as jar files. The bootstrap jars are used to bootstrap application configuration and web files into the content repository during the first deployment, and optionally on subsequent deployments depending on the deployment settings. 
  • Hippo Site
    site.war contains the delivery application (HST jars) as well as a repository connector which provides access to the content repository through the Hippo API jars in the shared classloader (see below).

• 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. For instance, because the site application communicates with the repository that is running inside the cms application, the interface to the repository (i.e. hippo-repository-api) must be shared between them.
  When creating a distribution with development data, the repository-data-development jar is 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.

Create a Project Distribution

A standard Hippo project based on Hippo's 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/myhippoproject-1.0.0-distribution.tar.gz 
-rw-r--r--  0 johndoe  staff    3632  8 Jun 12:37 conf/log4j2.xml
-rw-r--r--  0 johndoe  staff     850  8 Jun 12:37 conf/context.xml
-rw-r--r--  0 johndoe  staff 71556058  8 Jun 14:34 webapps/cms.war
-rw-r--r--  0 johndoe  staff 32210056  8 Jun 14:34 webapps/site.war
-rw-r--r--  0 johndoe  staff    16030  1 Jun 09:50 common/lib/geronimo-jta_1.1_spec-1.1.1.jar
-rw-r--r--  0 johndoe  staff    69246  9 Jun  2016 common/lib/jcr-2.0.jar
-rw-r--r--  0 johndoe  staff   521157  9 Jun  2016 common/lib/mail-1.4.7.jar
-rw-r--r--  0 johndoe  staff    23124  1 Jun 09:50 shared/lib/log4j-slf4j-impl-2.8.2.jar
-rw-r--r--  0 johndoe  staff    41203  1 Jun 09:50 shared/lib/slf4j-api-1.7.25.jar
-rw-r--r--  0 johndoe  staff   228154  1 Jun 09:50 shared/lib/log4j-api-2.8.2.jar
-rw-r--r--  0 johndoe  staff    16515  1 Jun 09:50 shared/lib/jcl-over-slf4j-1.7.25.jar
-rw-r--r--  0 johndoe  staff  1407853  1 Jun 09:50 shared/lib/log4j-core-2.8.2.jar
-rw-r--r--  0 johndoe  staff    41117  8 Jun 08:34 shared/lib/hippo-cms7-commons-4.0.0.jar
-rw-r--r--  0 johndoe  staff    43799  8 Jun 08:34 shared/lib/hippo-services-4.0.0.jar
-rw-r--r--  0 johndoe  staff   123801  8 Jun 08:34 shared/lib/hippo-repository-api-5.0.0.jar
-rw-r--r--  0 johndoe  staff    30815  8 Jun 08:34 shared/lib/hippo-repository-builtin-5.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 myhippoproject and project version 1.0.0):

-rw-r--r--  0 johndoe  staff   348269  8 Jun 11:31 shared/lib/myhippoproject-repository-data-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.