Creating a DX Core webapp with Maven

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

To complete this tutorial, you need Magnolia credentials to access the DX Core repositories.

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-dx-core-webapp as the base and exclude the following two modules from it:

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: info.magnolia.dx
artifactId: custom-dx-core-project
version: 1.0-SNAPSHOT
package: com.example
magnolia-bundle-version: {magnolia-latest-version}
project-name: custom-dx-core-project

Confirm the configuration by entering y.

The Maven archetype script creates this webapp skeleton:

custom-dx-core-project
├── custom-dx-core-project-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

In the dependencyManagement section, remove the Option A.
Uncomment the Option B.
In the repositories section, uncomment the repository with the id magnolia.enterprise.releases.

The resultant parent POM:

custom-dx-core-project/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-dx-core-project</artifactId>
  <name>custom-dx-core-project (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> (1)
    <dependencies>
      <!-- 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> (2)
        <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-dx-core-project-webapp</module>
  </modules>

</project>

1	Update dependency management in your project. Use the `6.3` version of the `magnolia-dx-core-bundle-parent`.
2	Make sure to specify and use the latest versions of the Maven plugins in your project.

Editing the webapp POM

In the webapp POM file, modify the dependencies section.

Uncomment the option iii.
Remove the other options (i and ii).

Exclude the Content Translation Support and Marketing Tags modules.
To exclude them, you have to add the exclusions section with an exclusion tag for each module. This should be done within the pom type dependency of the magnolia-dx-core-webapp.
(See also https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html.)

Here is the result:

custom-dx-core-project/custom-dx-core-project-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-dx-core-project</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  <artifactId>custom-dx-core-project-webapp</artifactId>
  <name>custom-dx-core-project: 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 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>
      <exclusions>
        <exclusion>
          <groupId>info.magnolia.translation</groupId>
          <artifactId>magnolia-content-translation</artifactId>
        </exclusion>
        <exclusion>
          <groupId>info.magnolia.translation</groupId>
          <artifactId>magnolia-content-translation-pages-integration-app</artifactId>
        </exclusion>
        <exclusion>
          <artifactId>info.magnolia.marketingtags</artifactId>
          <groupId>magnolia-marketing-tags</groupId>
        </exclusion>
      </exclusions>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId> (1)
        <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>

1	Make sure to specify and use the latest versions of the Maven plugins in your project.

When excluding a module from a webapp, you must check whether other modules, which are still part of the webapp, do not have runtime dependencies to the module you exclude. At the latest, you can discover any unsatisfied runtime dependency during the startup of your Magnolia webapp. Runtime dependencies are defined in the Magnolia Module descriptors.

Want to add your own dependencies?

Suppose you want to add, for example, the E-commerce dependencies outlined on this page: E-commerce Module. In that case, you must check whether the Magnolia bundle version is suitable for them. For instance, E-commerce 1.3.1 requires at least Magnolia 6.2.7; however, this tutorial uses the Magnolida bundle 6.2 when creating the webapp archetype. This can be resolved by increasing the Magnolia bundle version magnoliaBundleVersion in the parent POM file or decreasing the E-commerce version dependencies in the webapp POM file.

If you cannot find the necessary dependency information on a module page, please inspect the build log for missing dependencies when building the project with Maven.

Adding further resources

The skeleton produced by the Maven archetype has several folders which we have not used so far. This concerns especially the src folder in the webapp subdirectory. In the context of this tutorial page it is the custom-dx-core-project/custom-dx-core-project-webapp/src folder. This folder has the following subfolders:

src/
└── main
    └── webapp
        ├── WEB-INF
        │ ├── bootstrap
        │ │ ├── author
        │ │ ├── common
        │ │ └── public
        │ └── config
        │ └── default
        └── docroot

If you leave these subfolders empty, Maven takes the content from the imported webapp, that is the magnolia-dx-core-webapp.

The magnolia-dx-core-webapp inherits from the magnolia-community-webapp.

Customizing the `magnolia.properties` file

In this step, you add the (default) magnolia.properties file and customize the magnolia.resources.dir property in it.

What is `magnolia.resources.dir`?

magnolia.resources.dir is a property defining the directory from which resources are loaded in a Magnolia instance. This directory is used for file-based resources such as light modules and for overriding classpath resources. The property is configured in WEB-INF/config/default/magnolia.properties and its default value is $magnolia.home/modules. To see the current value of the property, go to the Config Info tab in the About Magnolia app.

You can use symbolic links (symlinks or soft links) in the resources directory to include light modules located elsewhere on your system.

Set the magnolia.resources.filesystem.observation.excludedDirectories property to exclude directories from being observed for changes. (See the table in the Configuration management: Defining properties section.)

Create the magnolia.properties file in the following folder: custom-dx-core-project/custom-dx-core-project-webapp/src/main/webapp/WEB-INF/config/default/.
As the file’s contents, reuse the version from our git repository for the custom-dx-core-project-webapp.
Go to the line which sets the magnolia.resources.dir property.
Assign the property a value which fits the requirements of your projects. Example:
```
magnolia.resources.dir=/Users/johndoe/dev/light-modules
```

In the next and final step you build the webapp.

Building the project

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

cd custom-dx-core-project
mvn clean install

The mvn command should finish with the BUILD SUCCESS message.

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

Congratulations. You’ve built your own custom webapp based on the DX Core webapp.

Creating a DX Core webapp with Maven

Introduction

Creating the webapp skeleton

Editing the parent POM

Editing the webapp POM

Adding further resources

Customizing the magnolia.properties file

What is magnolia.resources.dir?

Building the project

Location

Main doc sections

Customizing the `magnolia.properties` file

What is `magnolia.resources.dir`?