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.
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.
List of webapps
Magnolia provides the following stand-alone, pre-configured Apache Tomcat server that does not include a webapp:
A preconfigured Tomcat server ready to be used with any Magnolia webapp.
Magnolia provides the following webapps and bundles.
To get the complete list of the modules in each webapp or bundle, look at the corresponding POM file of the bundle.
DX Core
Artifact
Usage
dx-core-webapp
This is the DX Core webapp for projects. Use dx-core-webapp for local Magnolia Cloud development. (If you are a partner, see dx-core-cloud-webapp below).
Add a tomcat-bundle classifier to use with Apache Tomcat
travel-demo-webapp
DX Core webapp plus the Travel Demo for evaluation purposes.
Add a tomcat-bundle classifier to use with Apache Tomcat.
dx-core-cloud-webapp
For internal and partner cloud Magnolia usage.
Partners should use dx-core-cloud-webapp for local Magnolia Cloud development or when creating a custom cloud bundle for a customer
Use dx-core-webapp for local Magnolia Cloud development.
Community
Artifact
Usage
magnolia-empty-webapp
This is the most basic Magnolia webapp. Use this as a basis for your custom webapp.
magnolia-community-webapp
Complete Magnolia Community Edition webapp for community projects.
travel-demo-community-webapp
Community Edition webapp plus the Travel Demo for evaluation purposes.
travel-demo-community-webapp with tomcat
Community Edition webapp plus the Travel Demo for evaluation purposes bundled with Apache Tomcat.
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 Magnolia Maven setup^ page.
When creating a custom webapp, you have to decide whether your webapp will contain DX Core modules or only Community Edition modules.
If you go for the DX Core, you need credentials to access the DX Core repositories on Nexus and you also need a DX Core license to run the DX Core webapps.
If you don’t have these credentials yet, but want to try out the Magnolia DX Core, 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:
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
two:
magnolia-community-webapp
magnolia‑dx-core‑webapp
In the
Creating
a DX Core webapp with Maven part of this tutorial, the
magnolia-dx-core-webapp is used 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
Create a webapp skeleton from a Magnolia Maven archetype.
Modify the POM files according to your needs.
Add additional resources, if necessary.
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.
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:
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 DX Core) 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:
Parameter
Sample
Notes
groupId
com.example
It typically reflects the name or domain of your company or projects.
artifactId
custom-project-minimal
Project-specific identifier.
version
1.0-SNAPSHOT
Project version. Typically, when creating a new project, use the value suggested, 1.0-SNAPSHOT.
package
com.example
Package name for Java classes reflecting both your company (or domain) and the specific project.
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.3.2
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
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 a BUILD SUCCESS message.
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 content of the parent POM file, generated for bundle version 6.2:
custom-project-minimal/pom.xml
<?xml version="1.0" encoding="UTF-8" standalone="no"?><projectxmlns="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>{magnolia-latest-version}</magnoliaBundleVersion><javaVersion>{base-java-version}</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 DX CORE. --><!--
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-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/repository/public</url><snapshots><enabled>true</enabled></snapshots></repository><!-- IF YOU NEED MODULES FROM THE ENTERPRISE VERSION, UNCOMMENT THE FOLLOWING REPOSITORY --><!--
<repository>
<id>magnolia.nexus.enterprise</id>
<url>https://nexus.magnolia-cms.com/repository/enterprise</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>Copy
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.
Use the properties section to define versions. The section may the
serve as a central part for organizing all versions required by your
project.
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.
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 (Magnolia release 6.3.2) to understand what exactly
you inherit with Option A.
Use the Option B to inherit dependency management for a Magnolia
DX Core webapp.
Importing the DX Core dependency management section also indirectly
imports the CE dependency management.
Have a look at the
parent
POM of the DX Core (Magnolia release 6.3.2) to understand what exactly
you inherit with Option B. To access the parent POM of the EE bundle
on Git, you need DX Core credentials.
Also, use the dependencyManagement section to define the versions of
other modules which you want to add to the webapp.
<?xml version="1.0" encoding="UTF-8"?><projectxmlns="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-dx-core-webapp --><!-- Dependencies versions are already imported by parent pom. Requires "Option B" in the parent pom. --><!--
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-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>Copy
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:
magnolia-empty-webapp
magnolia-community-webapp
magnolia-dx-core-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: