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 bootstrap-configuration and bootstrap-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 content, the bootstrap-content 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 bootstrap content
• dist-with-content to create a distribution with bootstrap content

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

Create a Project Distribution without Content

To create a distribution without content 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    4986 30 Aug 11:11 conf/log4j.xml
-rw-r--r--  0 johndoe  staff    5016 30 Aug 11:11 conf/log4j.dtd
-rw-r--r--  0 johndoe  staff     853 30 Aug 11:11 conf/context.xml
-rw-r--r--  0 johndoe  staff 72462385 30 Aug 12:11 webapps/cms.war
-rw-r--r--  0 johndoe  staff 32206354 30 Aug 12:11 webapps/site.war
-rw-r--r--  0 johndoe  staff    15649  9 Jun 12:26 common/lib/geronimo-jta_1.1_spec-1.1.jar
-rw-r--r--  0 johndoe  staff    69246  9 Jun 12:26 common/lib/jcr-2.0.jar
-rw-r--r--  0 johndoe  staff   521157  9 Jun 12:26 common/lib/mail-1.4.7.jar
-rw-r--r--  0 johndoe  staff     8869  9 Jun 12:26 shared/lib/slf4j-log4j12-1.7.6.jar
-rw-r--r--  0 johndoe  staff    28688  9 Jun 12:21 shared/lib/slf4j-api-1.7.6.jar
-rw-r--r--  0 johndoe  staff   489884  9 Jun 12:26 shared/lib/log4j-1.2.17.jar
-rw-r--r--  0 johndoe  staff    16515  9 Jun 12:26 shared/lib/jcl-over-slf4j-1.7.6.jar
-rw-r--r--  0 johndoe  staff    39590 16 Jun 11:20 shared/lib/hippo-cms7-commons-3.0.0.jar
-rw-r--r--  0 johndoe  staff    33927 16 Jun 11:20 shared/lib/hippo-services-3.0.1.jar
-rw-r--r--  0 johndoe  staff   121577 30 Aug 11:26 shared/lib/hippo-repository-api-4.0.2.jar
-rw-r--r--  0 johndoe  staff    24412 30 Aug 11:26 shared/lib/hippo-repository-builtin-4.0.2.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 Content

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

mvn clean verify
mvn -P dist-with-content

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 content, 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-bootstrap-content-1.0.0.jar

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.