This page describes how to install and setup Apache Maven for DX Core projects, Community Edition projects, as well as for Magnolia staff.

This setup ensures that Magnolia modules and webapps are downloaded from our Nexus server, with appropriate access credentials.

To access Magnolia community modules and webapps in maintenance mode, follow the instructions for DX Core, using magnolia-enterprise settings.


 

Prerequisite: Java

Make sure you have installed a JDK (Java Development Kit). Magnolia 5.5+ requires Java 1.8 or higher.

Installing Maven

Download and Install Maven 3. Follow the OS-specific installation instructions from the Maven website (e.g. setting PATH environment variable).

Note for Windows users

Users of Windows 10 and Windows 11 have reported issues with Maven releases later than 3.8.1.

If you receive a java.lang.NoSuchMethodError when running the nexus-m2settings-maven plugin we recommend trying Maven 3.8.1.


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:
mvn -v

Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T17:41:47+01:00)
Maven home: /Library/Maven/apache-maven-3.3.9
Java version: 1.8.0_151, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_151.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.13.1", arch: "x86_64", family: "mac"

Maven keeps your user configuration and local repository under the ${user.home}/.m2/ directory. See also Configuring Maven.

Setting up credentials

Community Edition users may jump to the next section: Downloading Magnolia Maven settings.

Username and Password

You should have received credentials to connect to Magnolia's Nexus. This will give you access to enterprise and maintenance repositories. You may verify these credentials by logging in at https://nexus.magnolia-cms.com.

  

Password Encryption

We strongly recommend to set up Password Encryption, in order not to store your password unencrypted as plain text in Maven settings files. Follow this guide to create a master password and start encrypting existing server passwords.

To encrypt your Nexus credentials, choose one of the snippet below depending on the shell you are using, and execute the commands


Bash Shell version
mkdir -p ~/.m2 ; read -s -p 'Please enter your master Maven password: ' MASTPASS && \
echo "<settingsSecurity><master>`mvn --encrypt-master-password $MASTPASS`</master></settingsSecurity>" > ~/.m2/settings-security.xml ; \
unset MASTPASS
ZSH Shell version
mkdir -p ~/.m2; 
read -rs "MASTPASS?Please enter your master Maven password: "; 
echo "<settingsSecurity><master>`mvn --encrypt-master-password $MASTPASS`</master></settingsSecurity>"> ~/.m2/settings-security.xml; 
unset MASTPASS;

Enter a "master Maven password" when prompted for. Maven will create the file ~/.m2/settings-security.xml and store the master Maven password there.

Downloading Magnolia Maven settings

This will download and create the settings.xml file in the .m2  directory.
If this file already exists, Maven will create a backup copy (renamed as settings.xml-YYYYMMDDHHMMSS) before creating the new file.

Depending on your project, you will select a different settings "template" to download.

Community Edition project settings

To set up Maven with the community settings, simply execute the following command:

mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:1.6.8:download -DnexusUrl=https://nexus.magnolia-cms.com -Dusername=anonymous -Dpassword=anonymous -DtemplateId=magnolia-community-public

Maven will download the resources from Nexus and set up the settings file. That's all.

DX Core project settings

After you have set up Password Encryption above, switch to your shell and run the following command:

mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:1.6.8:download -DnexusUrl=https://nexus.magnolia-cms.com -DtemplateId=magnolia-enterprise

Maven will download the resources from Nexus, prompt you to enter your Nexus credentials—i.e. the username and password which Magnolia provided you—and will finish the setup.

These settings also apply to former Magnolia Enterprise Edition.

Settings for Magnolia staff

Run the following command:

mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:1.6.8:download -DnexusUrl=https://nexus.magnolia-cms.com

After asking for your credentials, Maven will prompt you to choose a settings template. Choose the internal one.

Testing the Maven Settings

A simple way to test your settings: Try to build a project with Maven which is dependent on a Magnolia Enterprise module. You should be able to build it with the  -U  option.
If you do not have such a project, you may generate one with Maven archetypes, or use one from our git repository.

Test your Maven settings using a sample project

You will clone our sample project documentation-check-maven-settings, and build it.

open a terminal, change to a temporary directory and clone the documentation-check-maven-settings module from magnolia git:

mkdir tmp
cd tmp/
git clone https://git.magnolia-cms.com/git/documentation/documentation-check-maven-settings.git

Alternatively the documentation-check-maven-settings Project is available here: https://git.magnolia-cms.com/users/cmeier/repos/documentation-check-maven-settings/browse (You maybe need to ask Christoph Meierfor permission (wink) )

The git command should produce the following (or a similar) output:

Cloning into 'documentation-check-maven-settings'...
remote: Counting objects: 15, done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 15 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (15/15), done.
Checking connectivity... done.

Now change into the cloned module and build the project with the -U option:

cd documentation-check-maven-settings/
mvn clean install -U

Maven will print out all the downloaded artifacts. At the end it should display the "BUILD SUCCESS" message:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.467 s
[INFO] Finished at: 2014-12-11T11:54:27+01:00
[INFO] Final Memory: 22M/184M
[INFO] ------------------------------------------------------------------------


Third Party Repositories

Depending on the network infrastructure you work with, you will probably have to add further repositories to your settings.xml. 

Mirroring

If you have your own Repository Manager, the following are the repositories you can mirror:

  Notes:  

  1. You need a Magnolia account to access these repositories. For mirroring, please get a "robots" account with us.
  2. A few artifacts Magnolia uses which are not available in the Maven Central Repository.
  3. A few third-party artifacts we customized and released ourselves. We usually move back to regular releases when fixes are publicly released in these.

Known issues

Authentication problems

You can login to the wiki, but your credentials seem to be rejected by the Nexus template download.

Some characters such as the Euro "€" symbol used in a password may cause the issue. Try changing your password and see if that helps. If this doesn't help, ask for help in the Magnolia forum.

Can not download vaadin addons

Due to the Magnolia repository settings  - Maven may fail to download some vaadin-addons. You may see this error message:

The following artifacts could not be resolved: org.vaadin.addon:easyuploads:jar:7.0.0, org.vaadin.addons:aceeditor:jar:0.8.11, 
org.vaadin.addons:cssinject:jar:2.0.3, org.vaadin.addons:gwt-graphics:jar:1.0.0, org.vaadin.addons:ckeditor-wrapper-for-vaadin:jar:7.8.8: 
Could not find artifact org.vaadin.addon:easyuploads:jar:7.0.0
If this happens - you should add the following snippet to the pom file of your project:
<repositories>
 <repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons</url>
  </repository>
</repositories>


12 Comments

  1. Pete Ryland

    Please note that nexus should be accessed via https only due to man in the middle attacks.  Http access will shortly be switched off.

  2. Razvan

    Is / will there be a similar setup tutorial for Gradle?

    1. Christoph Meier

      Hello Razvan

      On the Magnolia wiki you will find no "Gradle setup" page.
      And i as far as i know it is not planned.
      We focus here on Maven.

      However, you are highly welcomed to write such a page at the Community Wiki.

       

  3. Christopher Chard

    Hey guys,

    I am having trouble downloading from Nexus. After the username / pw prompt I get this:


    [INFO] Connecting to: https://nexus.magnolia-cms.com (as my_username_at_magnolia_ad)
WARNING: An illegal reflective access operation has occurred
WARNING: Illegal reflective access by com.thoughtworks.xstream.core.util.Fields (file:/C:/Users/XZ4A05A/.m2/repository/com/thoughtworks/xstream/xstream/1.4.7/xstream-1.4.7.jar) to field java.util.TreeMap.comparator
WARNING: Please consider reporting this to the maintainers of com.thoughtworks.xstream.core.util.Fields
WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
WARNING: All illegal access operations will be denied in a future release
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  36.812 s
[INFO] Finished at: 2019-12-06T00:02:02+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.sonatype.plugins:nexus-m2settings-maven-plugin:1.6.8:download (default-cli) on project standalone-pom: Connection failed: com.sun.jersey.api.client.ClientHandlerException: java.net.UnknownHostException: Dies ist normalerweise ein zeitweiliger Fehler bei der Auflösung von Hostnamen. Grund ist, dass der lokale Server keine Rückmeldung vom autorisierenden Server erhalten hat (nexus.magnolia-cms.com): Unknown host Dies ist normalerweise ein zeitweiliger Fehler bei der Auflösung von Hostnamen. Grund ist, dass der lokale Server keine Rückmeldung vom autorisierenden Server erhalten hat (nexus.magnolia-cms.com) -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException


    I tried this:

    • Password I received from Magnolia
    • Encrypted password I created
    • Changed password to something not containing any symbol characters (just letters and numbers)

    Nothing works. Please help! (smile)


    Thank you! 

    Cheers

    Chris

  4. Christoph Meier

    Christopher Chard

    The setup actually should still work ... I have tried it out recently.

    What exactly have you tried when Maven was "having trouble downloading"?

    What steps of the procedure here had you executed before you started the command which failed?

    As a last hint for now:
    You should "ditch" (e.g. by renaming) an existing .m2/settings.xml - since that could interfere with what you are trying to achieve with this set-up.
    Once this set-up process here was successful, you can customize the resulting settings.xml  again with some of your specific settings.

    Cheers,
     Christoph

  5. Bradley Andersen

    example project documentation-check-maven-settings DNE

    1. Sebastian Klingberg

      Hi Bradley Andersen, if you created the Maven Check Project, can you please make it available again or fix the documentation (smile) Thanks!

      https://git.magnolia-cms.com/projects/DOCUMENTATION does not include the `documentation-check-maven-settings` project (or it's an permission issue on my side)

      EDIT  
      Seems that the project is available here: https://git.magnolia-cms.com/users/cmeier/repos/documentation-check-maven-settings/browse (You maybe need to ask Christoph Meierfor permission (wink) )

      1. Christoph Meier

        Well, https://git.magnolia-cms.com/users/cmeier/repos/documentation-check-maven-settings is a fork of the original repo which was in DOCUMENTATION but which has been deleted.

        I can give read access to Sebastian. I even can enable 

        Allow users without a Bitbucket account to clone and browse this repository.

        But at the end it's still "my" git-repo. We probably should add that "check-repo" to another place, since I cannot guarantee that my fork will remain there forever.

        Martin Drápela - maybe we cam bring it back to its original location? 

        P.S.: I have granted you read&write access to my repo

      2. Christoph Meier

        Read access granted to Sebastian Klingberg ✅

      3. Christoph Meier

        F.Y.I.
        I have just raised magnolia-version (6.2.17) and java-version (1.8).

  6. Daniel Alonso

    Hi everybody!


    I have faced some problems during my local builds with maven and java 11 (java 11.0.2).


    To be more precised, I had the following problems:


    Peer not authenticated error

    Fixed by using: -Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true

    And

    No PSK available. Unable to resume

    For this, you cant upgrade to java 11 greater than 11.0.2 or use the following jvm params:


    -Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2


    Sources:


    https://blog.neodoo.es/2014/01/22/peer-not-authenticated-en-maven/

    https://stackoverflow.com/questions/52574050/javax-net-ssl-sslexception-no-psk-available-unable-to-resume

    1. Mikaël Geljić

      Thanks! That one is quite an oldie yeah; more recent JDKs are definitely fine. Any reason you got 11.0.2 specifically? It seems jdk-11.0.17+8 is the latest, via Eclipse Temurin (formerly AdoptOpenJDK).