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.
Make sure you have installed a Java JDK SE (Java Development Kit Standard Edition). Please use version 1.7 or higher.
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:
- Open a terminal or a shell.
- Issue the command mvn -v
Depending on the actual hardware configuration of your computer, the command should produce an output similar to this:
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:
- Community Edition (CE)
- Enterprise Edition (EE)
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
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.
.m2 Directory and Its Typical Location
.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:
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.
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
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:
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:
where the <template> may be one of the following options:
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.
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:
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).
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.
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:
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
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
To test build a project using the
open a terminal, change to a temporary directory and clone the
documentation-check-maven-settings module from magnolia git:
git command should produce the following output:
Now change into the cloned module and build the project with the -U option:
Maven will print out all the downloaded artifacts. At the end it should display the "BUILD SUCCESS" message:
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:
- https://nexus.magnolia-cms.com/content/repositories/magnolia.public.releases/ 1
- https://nexus.magnolia-cms.com/content/repositories/magnolia.public.snapshots/ 1
- https://nexus.magnolia-cms.com/content/repositories/magnolia.forge.releases/ 1
- https://nexus.magnolia-cms.com/content/repositories/magnolia.forge.snapshots/ 1
- https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases/ 2
- https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.snapshots/ 2
- https://nexus.magnolia-cms.com/content/repositories/thirdparty.customized/ 3
- https://nexus.magnolia-cms.com/content/repositories/thirdparty.licensed/ 4
- These repositories will eventually be synced to the Maven Central Repository so watch for changes to this page.
- You need a Magnolia account to access these repositories. Please get a "robots" account with us.
- 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.
- A few artifacts Magnolia uses which are not available in the Maven Central Repository.
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:If this happens - you should add the following snippet to the pom file of your project: