Magnolia 6.0 reached end of life on June 26, 2019. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

This tutorial explains how you can create custom Magnolia webapps with Maven. Using Maven allows you to customize your webapps with the POM files, which can be tracked with a version control system like Git. A tailored webapp makes building and deploying faster and has a positive impact on the performance of your instances. With Maven, you can streamline your Magnolia project to meet the specific demands of the project.

If you just want to try out Magnolia, follow instead the tutorial called How to get and adapt a bundle with Magnolia CLI.

Introduction

What is a webapp?

A Java Web Application (webapp) is a collection of servlets, other Java classes, static resources such as HTML pages, other resources, and meta information that describes the webapp bundled together. You can run a webapp on a servlet container. A Java webapp has a typical structure. It can be packaged as a WAR file. A webapp usually contains already packed portions called libraries or modules as JAR files.

Magnolia provides several preconfigured webapps and bundles. Some of them are ideal candidates as a starting point to build your custom webapp.

 Click to display a list of the preconfigured webapps and bundles provided by Magnolia.

Magnolia provides the following stand-alone, pre-configured Apache Tomcat server that does not include a webapp:

Artifact

Download


Usage / purpose

magnolia-tomcat-barebone

A preconfigured Tomcat server ready to be used together with any Magnolia webapp.


Magnolia provides the following webapps and bundles.

Artifact


 Download


 With Travel demo


 With EE Standard modules


 With EE Pro modules


 With Apache Tomcat

UsageModule summary1
Cloud edition






magnolia-cloud-webapp


(tick)(tick)
The standard Magnolia cloud offer bundles a selection of enterprise-level modules, including connectors enabling you to integrate third-party systems, tools and data sources.See Supported modules in the cloud.

magnolia-cloud-dev-webapp


(tick)(tick)


Enterprise level webapp specifically built for testing Magnolia Cloud development work locally.See Supported modules in the cloud .
magnolia-cloud-headless-webapp


(tick)(tick)
Bundles a lighter selection of enterprise-level modules enabling you to create content and use it in headless deployment scenarios.See Supported modules in the cloud - Headless cloud bundle modules .
Community edition

magnolia-empty-webapp





This is the most basic Magnolia webapp. Use this as a base for custom tailored webapp.Core modules from main and ui, Cache (core and ehcache), Pages, Resources, Publishing, Security and Scheduler.

magnolia-community-webapp





Complete Magnolia community edition webapp; no demo project.Same as magnolia-empty-webapp plus:
Cache tools,  Cache Browser, Categorization, Commenting, Contacts, DAMFind Bar, Form , Groovy, Mail, Messages, MTE , REST and Site.

magnolia-community-demo-webapp

(tick)


Same as magnolia-community-webapp plus the travel demoTravel demo community edition 2
magnolia-community-demo-bundle

(tick)

Tomcat-bundle including magnolia-bundled-webapp and travel demoTravel demo community edition 2

Enterprise Standard edition

magnolia‑enterprise‑standard‑webapp


(tick)

Same as magnolia-community-webapp plus Enterprise Standard modules; no demo

Backup, Content Dependencies, Content Translation Support, Diff, Marketing Tags, Personalization, Privacy module, Publishing Transactional, Soft Locking and Workflow.

magnolia‑enterprise‑standard‑demo‑webapp

(tick)(tick)

Same as magnolia‑enterprise‑standard‑webapp plus the travel demoTravel demo Enterprise Standard edition 3
Enterprise Pro edition  

magnolia-enterprise-pro-webapp


(tick)(tick)
magnolia-enterprise-standard-webapp plus Enterprise Pro module(s); no demo

Backup, Content Dependencies, Content Editor, Content tagging, Content Translation Support, Diff, Image Recognition module, Marketing Tags, PersonalizationPrivacy module Publishing Transactional, Soft Locking, Workflow and Multisite.

magnolia-enterprise-pro-demo-webapp

(tick)(tick)(tick)
magnolia-enterprise-pro-webapp plus the travel demoTravel demo enterprise pro edition 4
magnolia-enterprise-pro-demo-bundle

(tick)(tick)(tick)
Tomcat bundle with magnolia-enterprise-webapp including travel demoTravel demo Enterprise Pro edition 4
magnolia-enterprise-installer

(tick)(tick)(tick)
Installer for magnolia-enterprise-pro-demo-bundle

magnolia-enterprise-weblogic-webapp

(tick)(tick) 5(tick)
Webapp based on magnolia-enterprise-webapp including travel demo; tuned for Weblogic without workflow 5Travel demo Enterprise Pro edition 4

magnolia-enterprise-websphere-webapp

(tick)(tick) 5(tick)
Webapp based on magnolia-enterprise-webapp including travel demo; tuned for Websphere without workflow 5Travel demo Enterprise Pro edition 4

(1) The module summary does not list all modules but provides a good summary. To get the complete list of the modules, look at the corresponding pom file of the bundle.
(2) Travel demo Community edition contains the following modules: magnolia-travel-demo, magnolia-travel-tours.
(3) Travel demo Enterprise Standard edition contains the following modules: magnolia-travel-demo, magnolia-travel-tours, magnolia-travel-demo-personalization, magnolia-travel-demo-marketing-tags.
(4) Travel demo Enterprise Pro edition contains the following modules: magnolia-travel-demo, magnolia-travel-tours, magnolia-travel-demo-personalization, magnolia-travel-demo-marketing-tags, magnolia-travel-demo-multisite.
(5) Both magnolia-enterprise-weblogic-webapp and magnolia-enterprise-websphere-webapp contain all Enterprise Standard and Pro modules but not those for workflow.


Requirements

We assume that you are familiar with Maven and the basics of POM files. Your Maven settings should comply with the Magnolia Maven setup, which provides access to the Magnolia Nexus repositories, and thus ensures that you can build the webapps described in the examples. If you are new to Magnolia, we recommend that you first carefully follow the Maven setup page.

When creating a custom webapp, you have to decide whether your webapp will contain Enterprise modules or only Community edition modules. If you go for the Enterprise Edition, you need credentials to access the Enterprise repositories on Nexus and you also need an Enterprise license to run the Enterprise webapps. If you don't have the Enterprise credentials yet, but want to try out the Magnolia Enterprise Edition, apply for a trial license.

Possible approaches

This section describes two approaches to define a custom webapp with Maven. For both of them, keep in mind the following:

Best practice

To create a custom Magnolia webapp, always start with a preconfigured Magnolia webapp.

A minimal webapp and adding modules

If your aim is a minimalistic webapp, we recommend using the magnolia-empty-webapp as a base for your webapp project. it is also the base for every Magnolia webapp and provides the essentials such as the Core and UI modules. This approach is applied on the subpage Creating a minimal webapp with Maven. It could be suitable for you, if you aim at creating a custom headless instance.

A feature-rich webapp and excluding modules

Most of the preconfigured Magnolia webapps come with a feature-rich set allowing you to accomplish a number of different tasks and run complex websites. The most prominent preconfigured Magnolia webapps are these:

  • magnolia-community-webapp
  • magnolia‑enterprise‑standard‑webapp
  • magnolia-enterprise-pro-webapp

The second example — Creating an EE Pro webapp with Maven — uses the magnolia-enterprise-pro-webapp as a starting point. We then exclude some modules which are not necessary for the example use case.

When creating a feature-rich webapp, you cannot only exclude modules, you also need to add additional modules. Usually, it is common to do both, exclude and add modules.

Procedure overview

  1. Create a webapp skeleton from a Magnolia Maven archetype.
  2. Modify the POM files according to your needs.
  3. Add additional resources, if necessary.
  4. Build the webapp.

Creating an archetype-based webapp skeleton

Just as Maven provides archetypes to create a typical skeleton for Maven projects, Magnolia too provides an archetype to create a skeleton for a Magnolia Maven project. The Magnolia archetype comes with options for different tasks. Here, we use the magnolia-project-archetype. It is an archetype that creates a Magnolia project with its parent POM and a webapp with its own POM.

(warning) Before running the maven archetype command, please read How to use Magnolia Maven archetypes: Check Maven settings

If you are not familiar with the Maven archetype plugin, please also read How to use Magnolia Maven archetypes: The archetype plugin.

The archetype command

The first step to create your Maven-based custom webapp is running the archetype command. Change into the directory where you want to create the Maven project for the Magnolia webapp. In the directory, use a shell to run the following command:

mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE

While the archetype script is running, Maven prompts you to supply values for a list of parameters. Some of them are Maven-specific, others concern only Magnolia. In some cases, Maven suggests a value. To accept it, enter RETURN or specify your own value and press RETURN.

Executing the archetype command is the very first step you always have to take irrespective of the webapp edition you wish to create (Community or Enterprise) and the approach you want follow (minimal or feature-rich). The parameters you specify in the prompts have no influence on the edition type or the approach.

Archetype parameters

These are the parameters Maven prompts you with in the order they appear:

ParemeterExample valueExplanation
groupId 1)com.exampleIt typically reflects the name or domain of your company or projects.
artifactId 1)custom-project-minimalProject-specific identifier.
Maven artifact version1.0-SNAPSHOTProject version. Typically, when creating a new project, use the value suggested, 1.0-SNAPSHOT.
packagecom.example

Package name for Java classes reflecting both your company (or domain) and the specific project.

(info) For this archetype, this parameter is not used, but you must provide a value. You can use the value proposed by the archetype script.

magnolia-bundle-version

6.1.3

The Magnolia version from which your custom project inherits. If you are unsure, use the latest released version (see releases).

This version is used in the dependencyManagement section of the created POM files. The section indirectly manages all the versions of the Magnolia modules which go into the webapp.

project-name custom-project-minimal

Project name.

In many cases it is reasonable to use the same value as in artifactId.

1) See also the Maven Guide to naming conventions on groupId, artifactId, and version.

After entering a project-name value, the archetype script lists all the values you have provided. Now you can:

  • Confirm your choice by pressing RETURN. Maven will generate the skeleton based on your parameters.

  • Escape the running archetype script by pressing CTRL+C. The script terminates, not creating anything. To start again, execute the archetype command as described above. 

If you have confirmed your choice of parameters, the script finishes the build with the BUILD SUCCESS message:

 Click here to see an example of a Maven output
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: magnolia-project-archetype:RELEASE
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: custom-project-minimal
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: package, Value: com.example
[INFO] Parameter: packageInPathFormat, Value: com/example
[INFO] Parameter: magnolia-bundle-version, Value: 6.0
[INFO] Parameter: package, Value: com.example
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: project-name, Value: custom-project-minimal
[INFO] Parameter: artifactId, Value: custom-project-minimal
[INFO] Parent element not overwritten in ~/dev/repo/magnolia/webapps/custom-project-minimal/custom-project-minimal-webapp/pom.xml
[INFO] project created from Archetype in dir: ~/dev/repo/magnolia/webapps/custom-project-minimal
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:43 h
[INFO] Finished at: 2019-01-11T12:59:47+07:00
[INFO] Final Memory: 12M/142M
[INFO] ------------------------------------------------------------------------

The webapp skeleton

Maven generates the following webapp skeleton:

custom-project-minimal/
├── custom-project-minimal-webapp
│   ├── pom.xml
│   └── src
└── pom.xml
  • Line 3: The webapp's POM file, defining the modules going into the webapp.
  • Line 4: The src directory, containing more subfolders. In Example 2, you add more resources to this directory.
  • Line 5: The parent (actually the root) POM file of the created project. This POM file manages the dependencies.

The POM files are the central pieces of the skeleton. Make sure you understand these files since you must adapt them in the examples to define the custom webapps.

Parent POM

The contents of the parent POM file:

custom-project-minimal/pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>custom-project-minimal</artifactId>
  <name>custom-project-minimal (parent pom)</name>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <properties>
    <magnoliaBundleVersion>6.0</magnoliaBundleVersion>
    <javaVersion>1.8</javaVersion>
  </properties>

  <!-- Fill the following in, so you can use the release plugin -->
  <scm>
    <connection/>
    <developerConnection/>
    <url/>
  </scm>

  <dependencyManagement>
    <dependencies>

      <!-- Option A -->
      <!-- Importing dependencyManagement of CE bundle. -->
      <dependency>
        <groupId>info.magnolia.bundle</groupId>
        <artifactId>magnolia-bundle-parent</artifactId>
        <version>${magnoliaBundleVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>

      <!-- Option B -->
      <!-- If you want to use the Enterprise Edition. -->
      <!--
      <dependency>
        <groupId>info.magnolia.eebundle</groupId>
        <artifactId>magnolia-enterprise-bundle-parent</artifactId>
        <version>${magnoliaBundleVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      -->
    </dependencies>
  </dependencyManagement>


  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          <source>${javaVersion}</source>
          <target>${javaVersion}</target>
        </configuration>
      </plugin>
    </plugins>

    <!-- default resources configuration which will filter your module descriptors -->
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <includes>
          <include>**/*</include>
        </includes>
      </resource>
      <resource>
        <filtering>true</filtering>
        <directory>src/main/resources</directory>
        <includes>
          <include>META-INF/magnolia/*</include>
        </includes>
      </resource>
    </resources>
  </build>

  <repositories>
    <repository>
      <id>magnolia.public</id>
      <url>https://nexus.magnolia-cms.com/content/groups/public</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
    <!-- IF YOU NEED MODULES FROM THE ENTERPRISE VERSION, UNCOMMENT THE FOLLOWING REPOSITORY -->
    <!--
    <repository>
      <id>magnolia.enterprise.releases</id>
      <url>https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    -->
    <repository>
      <id>vaadin-addons</id>
      <url>https://maven.vaadin.com/vaadin-addons</url>
    </repository>
  </repositories>

  <modules>
    <module>custom-project-minimal-webapp</module>
  </modules>
</project>
Depending on the requirements of your project, the properties and the dependencyManagement sections may need some adjustments.

Properties

The properties section is where you define values such as versions. You can use the section in both the parent POM and the webapp POM.

Best practice

Use the properties section to define versions. The section may the serve as a central part for organizing all versions required by your project.
On lines 10-13 in the file embedded above, for example, the archetype adds the magnoliaBundleVersion property. 

Dependency management

In the dependencyManagement section, you define the artifact dependencies that you also add to the module in the webapp POM. See lines 22-47 in the file embedded above.

In the skeleton,Option A and Option B were created, the latter as a comment.

  • Use the Option A to inherit dependency management for a Magnolia Community Edition (CE) webapp. 
    Have a look at the parent POM of the CE bundle to understand what exactly you inherit with Option A.

  • Use the Option B to inherit dependency management for a Magnolia Enterprise Edition (EE) webapp.
    Importing the EE dependency management section also indirectly imports the CE dependency management.
    Have a look at the parent POM of the EE bundle to understand what exactly you inherit with Option B. To access the parent POM of the EE bundle on Git, you need EE credentials.

Also, use the  dependencyManagement section to define the versions of other modules which you want to add to the webapp.

Webapp POM

The contents of the webapp POM file:

custom-project-minimal/custom-project-minimal-webapp/pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>custom-project-minimal</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  <artifactId>custom-project-minimal-webapp</artifactId>
  <name>custom-project-minimal: webapp</name>
  <packaging>war</packaging>
  <dependencies>
    <!--
     Add your project specific dependencies here:
     A custom webapp typically is based on a magnolia webapp. The most simple and reduced bundle to start with is the "magnolia-empty-webapp" (see "option i" below).
     To see a complete list of preconfigured Magnolia webapps, have a look at https://documentation.magnolia-cms.com/display/DOCS/Bundles+and+webapps
     => Please just use one of the four below listed options!
     Make sure to use the appropriate option (A or B) in the parent pom
    -->

    <!-- option i - magnolia-empty-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-empty-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia</groupId>
      <artifactId>magnolia-empty-webapp</artifactId>
      <type>pom</type>
    </dependency>


    <!-- option ii - magnolia-community-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option A" in the parent pom. -->
    <!--
    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.bundle</groupId>
      <artifactId>magnolia-community-webapp</artifactId>
      <type>pom</type>
    </dependency>
    -->


    <!-- option iii - magnolia-enterprise-standard-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. -->
    <!--
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-standard-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-standard-webapp</artifactId>
      <type>pom</type>
    </dependency>
    -->


    <!-- option iv - magnolia-enterprise-pro-webapp -->
    <!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. -->
    <!--
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>pom</type>
    </dependency>
    -->

  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
          <dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Dependencies

Finally, in the dependencies section of the webapp POM, you assemble the modules which should be part of the webapp. Since you are using a preconfigured Magnolia webapp as the base, the Magnolia archetype creates and adds the following options to the webapp POM (lines 13-83 above):

  • magnolia-empty-webapp
  • magnolia-community-webapp
  • magnolia-enterprise-standard-webapp
  • magnolia-enterprise-pro-webapp

Each of these options has a dependency to two artifact types  –  pom and war.

Besides adding an existing webapp, you typically also add other dependencies to single modules.

Examples

For examples of creating custom webapps with Maven, see the following pages:

  • No labels