Creating a minimal webapp with Maven

This tutorial page explains how you can create a minimalistic Magnolia headless webapp from a Magnolia Maven archetype. If you’d like to try creating a full-featured DX Core webapp, see Creating a DX Core webapp with Maven. For a general overview page, please refer to Creating a custom webapp with Maven.

To complete this tutorial, you need to install Maven and configure the Magnolia Maven settings.

Introduction

Using Maven to create a webapp allows you to customize your webapp through 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.

In the steps below, you use the magnolia-empty-webapp as the base and add the following modules to it:

Magnolia Rest modules
Magnolia Assets subapp, which also brings in other modules from the Magnolia Digital Asset Management (DAM)
Site module
jsonfn

The resulting webapp could be used to run Magnolia in a headless approach.

This set of modules is just an example. We cannot guarantee that the given module composition is best practice for a headless bundle. With the exception of the jsonfn module, dependency management and versioning of all the other modules on the list is already handled by the dependencyManagement section of the webapp’s parent POM file. The dependency of the jsonfn module has to be set manually.

Creating the webapp skeleton

Start by running the Magnolia Maven archetype command to create a skeleton of your webapp.

Create and switch to a directory where you want to create the new webapp, for example ~/dev/repo/magnolia.

Open a shell and enter the following Maven command:

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

When prompted to supply values for archetype parameters, enter the following:

groupId: com.example
artifactId: custom-project-minimal
version: 1.0-SNAPSHOT
package: com.example
magnolia-bundle-version: 6.2.17
project-name: custom-project-minimal

Confirm the configuration by entering Y.

The Maven archetype script creates this webapp skeleton:

custom-project-minimal
├── custom-project-minimal-webapp
│ ├── pom.xml
│ └── src
└── pom.xml

Line 3: The webapp POM.
Line 5: The parent POM.

In the next two steps, you edit the two pom.xml files.

Editing the parent POM

Edit the properties section. Add a new property called jsonfnVersion and give it the value 1.0.8.
```
<jsonfnVersion>1.0.8</jsonfnVersion>
```

Edit the dependencyManagement section.

Remove the commented Option B.

Add a dependency section for the jsonfn module:

<dependency>
  <groupId>info.magnolia.templating</groupId>
  <artifactId>magnolia-jsonfn</artifactId>
  <version>${jsonfnVersion}</version>
</dependency>

Remove the other commented sections, as well as the sections that you do not need right now.

Here is the resultant parent POM:

custom-project-minimal/pom.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<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.2</magnoliaBundleVersion>
    <javaVersion>1.8</javaVersion>
    <jsonfnVersion>1.0.8</jsonfnVersion>
  </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>
      <dependency>
        <groupId>info.magnolia.templating</groupId>
        <artifactId>magnolia-jsonfn</artifactId>
        <version>${jsonfnVersion}</version>
      </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>
    <repository>
      <id>vaadin-addons</id>
      <url>https://maven.vaadin.com/vaadin-addons</url>
    </repository>
  </repositories>

<modules> <module>custom-project-minimal-webapp</module>
  </modules>
</project>

Editing the webapp POM

In the webapp POM, you have to modify the dependencies section.

Remove the commented option ii and option iii. Keep the option i, which imports the empty webapp.

Add the Magnolia REST module dependencies:

<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-integration</artifactId>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-services</artifactId>
</dependency>
<dependency>
  <groupId>info.magnolia.rest</groupId>
  <artifactId>magnolia-rest-content-delivery</artifactId>
</dependency>

Add the Assets app dependency:
```
<dependency>
  <groupId>info.magnolia.dam</groupId>
  <artifactId>magnolia-dam-app</artifactId>
</dependency>
```
Note that the magnolia-dam-app itself has other dependencies. However, you do not have to add them to the POM file. Maven resolves the dependencies while building the project and adds them to the webapp.

Add a dependency for the Site module:

<dependency>
  <groupId>info.magnolia.site</groupId>
  <artifactId>magnolia-site-app</artifactId>
</dependency>

Add a dependency for the jsonfn module:

<dependency>
  <groupId>info.magnolia.templating</groupId>
  <artifactId>magnolia-jsonfn</artifactId>
</dependency>

Resultant webapp POM:

custom-project-minimal/custom-project-minimal-webapp/pom.xml

<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>
    <dependency>
      <groupId>info.magnolia.rest</groupId>
      <artifactId>magnolia-rest-integration</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.rest</groupId>
      <artifactId>magnolia-rest-services</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.rest</groupId>
      <artifactId>magnolia-rest-content-delivery</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.dam</groupId>
      <artifactId>magnolia-dam-app</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.site</groupId>
      <artifactId>magnolia-site-app</artifactId>
    </dependency>
    <dependency>
      <groupId>info.magnolia.templating</groupId>
      <artifactId>magnolia-jsonfn</artifactId>
    </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>

In the next and final step you build your webapp.

Building the webapp

First, change into the root directory of the webapp project. Then, run the mvn command with the tasks clean and install:

cd custom-project-minimal
mvn clean install

The Maven command should finish with the BUILD SUCCESS message.

You can find the webapp in the custom-project-minimal/custom-project-minimal-webapp/target folder.

Tip

If you switch to the custom-project-minimal-webapp directory, you can run the Maven dependency tree command to see all modules and libraries which went into the webapp:

  mvn dependency:tree

Congratulations. You’ve built your own custom webapp based on the Magnolia empty webapp.