Page tree
Skip to end of metadata
Go to start of metadata

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).

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, execute the following command in your terminal or shell

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

and 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.5: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.5: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.5: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.

 Click here to expand how to test Maven settings with a sample project...

Test your Maven settings using a sample project

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

 Click here to expand to get the details about fetching documentation-check-maven-settings and building it to test the maven settings

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

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

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 third-party artifacts we customized and released ourselves. We usually move back to regular releases when fixes are publicly released in these.
  3. A few artifacts Magnolia uses which are not available in the Maven Central Repository.

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>http://maven.vaadin.com/vaadin-addons</url>
  </repository>
</repositories>


5 Comments

  1. 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. Is / will there be a similar setup tutorial for Gradle?

    1. 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. 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. 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