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

This page describes how to install and setup Apache Maven to get access to the Magnolia Maven repository (https://nexus.magnolia-cms.com) for users with

  • Community Edition (CE), and
  • Enterprise Edition (EE) 

licenses, as well as for

  • Forge-Dev users, and
  • Magnolia-internal users.

Proper Maven setup ensures that you can access Maven artifacts of Magnolia and other modules from our Nexus server. Please note that some of the instructions may be OS-specific.


 


Prerequisite: Java

Make sure you have installed a Java JDK SE (Java Development Kit Standard Edition). Please use version 1.7 or higher.

Installing Maven

To avoid compatibility issues, please use Apache Maven in version 3.2.3

Download and install Maven 3.2.3 binaries that will work for your OS. For OS-specific installation instructions, please consult the Apache Maven Project website. If you follow these OS-specific instructions, you will most probably have to set also some OS environment variables.

Verify that Maven 3.2.3 is installed

After the installation of files verify that Maven 3.2.3 has been installed correctly:

  1. Open a terminal or a shell.
  2. Issue the command mvn -v

Depending on the actual hardware configuration of your computer, the command should produce an output similar to this:

mvn -v

Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T22:58:10+02:00)
Maven home: /Applications/apache-maven-3.2.3
Java version: 1.7.0_79, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.7.0_79.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.11.4", arch: "x86_64", family: "mac"

Setting up Maven: General Notes

The Maven setup procedure depends on the user template (or profile) used to access Magnolia artifacts, and also on the OS you are using. The following user templates are supported:

  • Forge-Dev  
  • Community Edition (CE) 
  • Enterprise Edition (EE) 
  • Magnolia-internal 

In general, after setting up Maven, your home directory will contain a newly created .m2 directory where a local file repository and setting files (usually settings.xml and settings-security.xml) will be stored. A successful setup of Maven should display the line

"[INFO] BUILD SUCCESS"

on your screen together with additional details summarizing the build such as the name of the user template applied, build duration and timestamp, the location of the .m2 directory, and memory information.

The .m2 Directory and Its Typical Location

The .m2 directory, which Maven will use to store and access the local repository and the setting files, can be created

  • by Maven during the setup procedure, or
  • by the "master MAVEN password" encryption script (see further below)
  • manually (this possibility might help solve some setup problems for Linux users)

The location of the .m2 directory depends on your OS. Typically, the location will be as follows:

Mac/Users/<your-username>/.m2
WindowsC:\Documents and Settings\<your-username>\.m2
or
C:\Users\<your-username>\.m2 
Linux/home/<your-username>/.m2
In general
~/.m2

Username and Password

If you are a Community Edition user, you only have access to public resources. In this case Maven will connect you anonymously during the setup and both your username and your password will have the same form, "anonymous".

If you are an Enterprise Edition, Forge-Dev or Magnolia-internal user, you have received a specific username and a password to connect to Nexus, which will allow you to access also protected repositories. You may verify these credentials by going to https://nexus.magnolia-cms.com with a browser of your choice and logging in. If your credentials are correct, you will be able to log in to the server and your username will be displayed in the top right corner of the Nexus page.

  

The "master Maven password"

The "master Maven password" is a password used to encrypt your credentials (username and password) necessary to access specific Magnolia Nexus repositories. The first time you try to access data from a repository, Maven will ask you for these credentials. Normally, they would be stored in unencrypted form in the local settings.xml file. To improve on security, the script below can be run to encrypt the credentials and add them as tokens into the settings.xml file during the setup of Maven. Please note that the "master Maven password" has nothing to do with your Nexus password. When prompted for by the script, just choose a master Maven password.

EE users, Forge-Dev, and Magnolia internal users are strongly advised to encrypt their credentials (i.e. to setup the master Maven password) before initiating the Maven setup even though on some systems logging into Maven with unencrypted credentials may still be possible. 

(warning) On Linux, this encryption step is required since skipping it as a non-CE user will result in an error and the setup of Maven will fail. 

To encrypt your Nexus credentials, execute the following command in your terminal or shell

test -d ~/.m2 || mkdir ~/.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.

The Maven setup command

Maven setup can be initiated by the following command:

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

With the command in this form you will be asked later on to choose a Magnolia template you wish to use.

Alternatively, you can set the template directly by appending the -DtemplateId=<template> option to the mvn command:

mvn org.sonatype.plugins:nexus-m2settings-maven-plugin:1.6.5:download -DnexusUrl=https://nexus.magnolia-cms.com -DtemplateId=<template>

where the <template> may be one of the following options:

magnolia-forge-dev
magnolia-community-public
magnolia-enterprise
magnolia-internal-UEkeku77mdz

When you run the command for the first time, with or without the template option, at some point Maven will create the .m2 directory together with the settings.xml file in it. If this file already exists, Maven will create its backup copy (renamed as settings.xml-YYYYMMDDHHMMSS) before creating the new file.
(warning) In some cases you will have to run the setup command twice and merge the new file and the backup file manually, for example, in a scenario where you have user permissions for the Enterprise Edition repositories as well as for the Forge-Dev repositories.

Setting up Maven: The Templates

The setup procedures below are all explained using the Maven mvn command without the -DtemplateId=<template> option.

Community Edition (CE) Template

Under the CE license you only have access to public resources and you do not have to encrypt your Nexus username and password.
To setup Maven with the CE template, simply execute the following command:

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

Maven will download the resources from Nexus and ask you for a username and a password. Enter "anonymous" for both and choose the template magnolia-community-public. That's all. 

 

Forge-Dev, Enterprise Edition (EE), and Magnolia-internal Templates

Please make sure that you have encrypted your Nexus access credentials (for details, see the subsection The "master Maven password" above). 
(warning) If you are a Mac user who is setting up Maven for the first time or if there is no valid settings.xml file in the .m2 directory on your Mac, you need to first complete the above procedure which sets up Maven with the Community Edition (CE) template.

(warning) If you are a Linux user, just check that the directory .m2 exists in your home directory. It should be there as a result of executing the "master Maven password" encryption script described 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 

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

Testing the Maven Settings Under the Enterprise Template

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 clone the documentation-check-maven-settings from our git repository and build it with Maven.

Testing the Maven Settings Using the documentation-check-maven-settings

To test build a project using the documentation-check-maven-settings,

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

You Have Your Own Maven Repository

If you have your own Maven repository, the following are the repositories you can mirror:

  Notes:  

  1. These repositories will eventually be synced to the Maven Central Repository so watch for changes to this page.
  2. You need a Magnolia account to access these repositories. Please get a "robots" account with us.
  3. This will also possibly (and eventually) be synced to the Maven Central Repository: it contains a few third party artifacts we customized and released ourselves (for example a bugfix release of OpenWFE). We're working on making this obsolete, i.e use dependencies which are available in the Maven Central Repository.
  4. 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>

1 Comment

  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.