Add a Second Site Webapp - BloomReach Experience - Open Source CMS

Add a Second Site Webapp

Setting up multiple site web applications within the same project is intended to enable separate development teams working independently on their respective sites. Bloomreach recommends setting up multiple site web applications only in this specific development scenario.



Add a second site web application to your existing Bloomreach Experience Manager implementation project.


The tutorial assumes:

In addition, it is highly recommended to:


The second site webapp will be a separate Maven project with its own version management and release cycle but with a dependency on the 'parent' sub-project's CMS webapp.

In a real world development environment, the parent sub-project's artifacts would be deployed in your organizations Maven repository. For the purpose of this tutorial, you will use your local Maven repository as surrogate.

Following this tutorial, you will walk through a very basic multi-site development workflow scenario: create the second site webapp using the Maven archetype, add a feature to it, then migrate any platform code and/or configuration related to the new feature to the parent sub-project. The end result will be that the complete implementation project, including the parent sub-project and the site sub-project) is ready for an aggregate deployment in an environment.

Create the Maven Project for the Second Site Webapp

First, navigate to the directory containing the existing project (myproject) and run the following Maven command:

mvn clean install

This deploys the project's artifacts in your local Maven repository so they are available when your build the new site sub-project.

Navigate to a directory outside the existing project (e.g. its parent directory).

To create the second site webapp sub-project, type the command shown below. This will create a new folder with a name equal to the chosen artifactId, containing the generated sub-project. On Windows, run the command on a single line and leave out the line continuation characters ('\') or use '^' as continuation character.

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
-DarchetypeGroupId=org.onehippo.cms7 \
-DarchetypeArtifactId=hippo-site-project-archetype \
-DarchetypeVersion=14.0.0-2 \


mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.onehippo.cms7 -DarchetypeArtifactId=hippo-site-project-archetype -DarchetypeVersion=14.0.0-2 -DarchetypeRepository=

The archetype plugin will ask you to confirm a number of properties defining the Maven coordinates for both the new site sub-project and the existing parent sub-project:

Confirm properties configuration:
artifactId: mysiteproject
version: 0.1.0-SNAPSHOT
parentArtifactId: myproject
parentGroupId: org.example
parentVersion: 0.1.0-SNAPSHOT
projectName: My Site Project
 Y: : 

If you are just following the tutorial and using the archetype default settings, press Enter to continue. Otherwise, enter 'N', then enter the appropriate values for your project.

Build and run the site sub-project as you normally would for a single-site project:

cd mysiteproject
mvn clean verify
mvn -Drepo.path=./storage

Note that the site sub-project has its own CMS webapp (running at the usual URL, http://localhost:8080/cms/) which basically repackages the parent sub-project's CMS. This CMS webapp exists solely for the purpose of development within the site sub-project. The same is true for the repository-data/application module.

The site will run at http://localhost:8080/mysiteproject/ although at this point there is nothing there yet.

Add a Feature to the Second Site Webapp

You are now ready to develop and test features in the site sub-project. Because feature development is outside the scope of this tutorial, you will add an out-of-the-box feature from the Essentials library as an example.

Tip: before you add the feature, bring the site sub-project code under version control (e.g. Git) so you can easily 'diff' afterwards to see what changes introduced by the new feature need to be migrated to the parent sub-project.

Browse to the Essentials dashboard at http://localhost:8080/essentials/ and install the 'Events' feature from the library.

Rebuild and restart the site sub-project and check the CMS and the site (at http://localhost:8080/mysiteproject/) to verify that the feature is installed and working correctly.

Note that up to this point, you have worked in complete isolation from the parent sub-project, i.e. your changes do not affect it. This is important, as it allows the parent sub-project to continue its own lifecycle of development, deployment, etc. without interference from any development going on in the site sub-project.

Migrate CMS Configuration from the Site Sub-Project to the Parent Sub-Project

Once the new feature in the site sub-project is ready, any new code and/or configuration in the cms and repository-data/application modules must be migrated to the corresponding modules in the parent sub-project.

Adding the 'Events' feature did not introduce any CMS code, but it did add and modify several files within the repository-data/application module. 

The following files were added:

  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject.cnd
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject/basedocument.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject/eventsdocument.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/modules/validation.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/queries/templates/new-events-document.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/queries/templates/new-events-folder.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/cms.yaml

Move all of the above files over to the corresponding folder within myproject/repository-data/application (create subfolders if necessary).

The following files were modified:

  • mysiteproject/repository-data/application/src/main/resources/hcm-config/main.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/templates.yaml
  • mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/types.yaml

You will have to manually merge the contents of the above 3 files into their counterparts in myproject/repository-data/application:


      cnd: namespaces/myproject.cnd
      cnd: namespaces/mysiteproject.cnd

myproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/templates.yaml (only English translations shown, merge other languages in a similar way):

      # <snip/>
      new-resource-bundle: new resource bundle
      new-untranslated-folder: new untranslated folder
      new-news-document: new news item
      new-news-folder: new news item folder
      new-content-folder: new content folder
      new-content-document: new content document
      new-events-folder: new events folder
      new-events-document: new event
      # <snip/>
      # <snip/>

myproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/types.yaml (only English labels for eventsdocument shown, merge labels in other languages as well):

      jcr:primaryType: hipposys:resourcebundles
        # <snip/>
        # <snip/>
        # <snip/>
        # <snip/>
      jcr:primaryType: hipposys:resourcebundles
        # <snip/>
        # <snip/>
        # <snip/>
        # <snip/>
      jcr:primaryType: hipposys:resourcebundles
        jcr:primaryType: hipposys:resourcebundle
        jcr:name: Event
        mysiteproject:content: Content
        mysiteproject:date: Start date
        mysiteproject:enddate: End date
        mysiteproject:image: Image
        mysiteproject:introduction: Introduction
        mysiteproject:location: Location
        mysiteproject:title: Title
        # <snip/>
        # <snip/>
        # <snip/>

After merging the changes, delete the 3 files from mysiteproject/repository-data/application. You can also delete any resulting empty folders.

Rebuild (mvn clean install) and restart the parent sub-project and browse to the CMS. Navigate to the Content application and select Document Types from the dropdown. The mysiteproject namespace should be there and contain the Event document type.

Stop the parent sub-project.

Delete the site sub-project's storage folder, the rebuild and restart the site sub-project. Verify that all the Events functionality (with the platform configuration now inherited from the parent sub-project) is still there and working as expected.

At this stage, you may want to test an aggregate deployment of the parent and site sub-projects. In your local development environment, you can use the following Maven command to do this:

mvn,with-main-site -Drepo.path=./storage

Browse to the CMS and verify that both sites can be previewed in the Experience manager. Also verify that both the 'live' sites are available (on http://localhost:8080/site/ and http://localhost:8080/mysiteproject/) and fully functional.

If you want to deploy in a server environment (on-premise or Bloomreach Cloud), you need to create a distribution containing all three webapps (CMS and both sites). Add the mysiteproject webapp to the appropriate assembly file, for example:


<component xmlns="" xmlns:xsi=""

You can now create the distribution as usual:

mvn clean verify
mvn -P dist

Please note that content for the site sub-project is not included in the distribution and will therefore not be bootstrapped on deployment. If you want to bootstrap some initial content (such as the mysiteproject root folder and the events folder), you would need to move the relevant YAML files from mysiteproject/repository-data/application/src/main/resources/hcm-content to myproject/repository-data/application/src/main/resources/hcm-content. However, this would complicate development going forward so it may be better to create the content manually after the first deployment and keep the management of this type of repository data seperated between the sub-projects.

This completes a full multi site development workflow cycle.

Additional Reading

Multi Site Development Workflow

Configure Multiple Site Webapps in Bloomreach Cloud


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?