How to use Magnolia Maven archetypes

This page explains how to use Magnolia-specific Maven archetypes to jumpstart development of Magnolia Maven modules and projects.

Maven is a tool for managing project dependencies and building your Magnolia project.

This page describes how to configure Maven to download Magnolia modules and webapps from our Nexus server, with appropriate access credentials.

Install maven

Download and Install Maven. In order to verify Maven has been installed correctly:

  1. Open a terminal or a shell.

  2. Issue the command mvn -v. The command should produce an output similar to this:

    example
    mvn -v

Apache Maven 3.9.1 (2e17850...cc58f8)
Maven home: /usr/local/apache-maven-3.9.1
Java version: <JAVA_VERSION>, vendor: Eclipse Adoptium, runtime: path/to/install
Default locale: fr_FR, platform encoding: UTF-8
OS name: "<OPERATING_SYSTEM>"
    Maven keeps your user configuration and local repository under the ${user.home}/.m2/ directory. For more details, see Configuring Maven.

Set up Magnolia repositories

For DX Core projects, or for community releases in maintenance mode, add the following repository to your project POM (or Maven settings profile), and follow the next sections to set up authentication.

For more details, see Maven: Setting up Multiple Repositories.

DX Core 
<repositories>
  <repository>
    <id>magnolia.nexus.enterprise</id>
    <url>https://nexus.magnolia-cms.com/repository/enterprise</url>
  </repository>
</repositories>
Community edition 
<repositories>
  <repository>
    <id>magnolia.nexus.public</id>
    <url>https://nexus.magnolia-cms.com/repository/public</url>
  </repository>
   <repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons/</url>
  </repository>
 </repositories>

Create a master password (recommended)

We recommend you create a master password. However, this is not mandatory.

For more details, see Maven’s Password Encryption.

  1. Run the following command.

    mvn --encrypt-master-password

    This command produces an encrypted version of the password similar to the example below:

    {jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}

  2. Store the password in ~/.m2/settings-security.xml.

    <settingsSecurity>
  <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
</settingsSecurity>

Set up credentials in Maven settings

To set up or update your credentials for Maven:

  1. Log into Nexus with your regular credentials.

  2. Go to your profile. This is typically in the top corner with your username.

  3. Select User Token from the menu.

  4. Click Access user token.

    This prompts you to log in again. Upon successful login, your user tokens are displayed.

  5. If you have created a master password, encrypt your user token pass code:

    mvn --encrypt-password ${userTokenPassCode}

  6. Finally, store the token in the format shown here.

    <server>
  <id>magnolia.nexus.enterprise</id> (1)
  <!-- Token, not actual username / password -->
  <username>{userTokenNameCode}</username> (2)
  <password>{userTokenPassCode}</password> (3)
</server>
    1 The Magnolia enterprise Nexus repository. The id must match the repository id in your project POM or 'magnolia-repositories' profile in maven settings.
    2 Your name code user token from Nexus.
    3 Your pass code user token from Nexus. You may use your encrypted pass code token here.

Using Magnolia Maven archetypes

You need Maven to generate Magnolia project archetypes. To do so, add the following to your Maven settings.

<profiles>
  <profile>
    <id>magnolia-repositories</id>
    <activation>
      <activeByDefault>true</activeByDefault>
    </activation>
    <repositories>
      <!-- required for Magnolia Maven archetypes -->
      <repository>
        <id>magnolia.nexus.public</id>
        <url>https://nexus.magnolia-cms.com/repository/public</url>
      </repository>
    </repositories>
  </profile>
</profiles>
For more details, see Maven Archetypes and repositories.

The Archetype plugin

The Maven Archetype Plugin allows you to create a Maven project from an archetype – an existing template (a skeleton of files and directories).

The base plugin command is mvn archetype:generate.

  • For an overview of the parameters it accepts, see the archetype:generate page on the Apache Maven Project website.

  • For details on how the command works and how to use the interactive mode, see the Usage page on the site.

Option A

If you already know which Magnolia archetype you want to generate, the fastest way is to supply the archetype’s Maven coordinates (GAV) to the command line. For example:

mvn archetype:generate -DarchetypeGroupId=info.magnolia.maven.archetypes -DarchetypeArtifactId=magnolia-project-archetype -DarchetypeVersion=RELEASE
If you omit the archetypeVersion, the plugin automatically picks the oldest version.

Option B

By default, the archetype plugin collects a list of all possible archetypes, including those found at Maven Central. The list can be very long and it may take some time to generate it. To reduce the list only to available Magnolia archetypes, use the plugin command with the following filter option:

mvn archetype:generate -Dfilter=info.magnolia.maven.archetypes:magnolia
If you need to interrupt the command, press CTRL + C.

Magnolia Maven archetypes

Magnolia provides the following archetypes:

  • The magnolia-project-archetype generates a Magnolia project with a parent POM and a Magnolia webapp.

  • The magnolia-module-archetype generates a Magnolia Maven module. For details, please refer to the Modules page.

  • The magnolia-blossom-module-archetype generates a Magnolia Maven module with support for the Blossom module.

  • The magnolia-cloud-project-archetype generates a Magnolia project with both a parent POM and both the dev and shared directories. See Creating and deploying custom cloud bundles for more details.

Before generating a project, the archetypes ask you to supply values for the following parameters:

Required parameters Example value Notes

Maven groupId

com.example

Typically reflects the name or domain of your company or projects.

Maven artifactId

custom-project

Project-specific identifier.

Maven version

1.0-SNAPSHOT

Project version. Typically, when creating a new project, use the value suggested by Maven, for example 1.0-SNAPSHOT.

package

com.example

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

magnolia-bundle-version

6.2

Magnolia version to be used in your custom project.

project-name

Custom Project

Project name.

module-class-name

FoobarModule

Module name.

This is for module archetypes only.

blossom-version

3.2.1

The version of the Magnolia Blossom module.

This is for the blossom module archetype only.

Discontinued archetypes

As of version 1.2.5, the following archetypes have been discontinued. Older versions may still appear if you use the filter option.

  • The magnolia-forge-module-archetype, used to create a Magnolia module for the former Magnolia Forge (moved to GitHub: Magnolia Forge).

  • The magnolia-theme-archetype, used to create an STK (deprecated) theme module.

Which archetype version should I use?

Use the latest archetype release: 1.3.

Generated skeletons

A creation of a project typically results in the following skeleton, with a few more files created in src/main/webapp. For details, see Creating a custom webapp with Maven.

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

On the other hand, if you create a module, the skeleton will have a simpler structure (no multi-module Maven reactor), with a pre-generated Magnolia module descriptor and Java module class. See also Module structure.

custom-module/
├── pom.xml
└── src
    ├── main
    │ ├── java
    │ └── resources
    │ └── META-INF
    │ └── magnolia
    │ └── custom-module.xml
    └── test
Further reading
Magnolia
External
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules