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 will only have access to public resources, so please skip to the next chapter, "Setting up Maven: The Templates".

If you are an Enterprise Edition, Forge-Dev or Magnolia-internal user, you will 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

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.

Setting up Maven: The Templates

You should choose one of the setup procedures below, depending on the permission you have.

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.

Community Edition (CE) Template

To set up 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 -Dusername=anonymous -Dpassword=anonymous -DtemplateId=magnolia-community-public

Maven will download the resources from Nexus and set up the settings file. 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). 

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>

3 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. I see you rolled back my edit – will you please fix the command for encrypting Maven nexus credentials? If you copy paste you get "&amp;&amp;" when you probably want to have "&&" instead. Might also be worth pointing out this is for bash vs. other shells as well.

    1. Hi Thomas

      Sure, i will fix it. 
      My rollback was "quick & dirty", sorry about this.

      If you have valuable - i'm open and willing to add them.
      Basically, the command how it was there (besides the wrong &amp;) was tested on OSX and some  LINUX distributions. That's why i have rolled it back.