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.8 or higher (required for Magnolia 5.5+).
Download and install Maven 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 is installed
After the installation of files verify that Maven 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 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.
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.
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.
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:
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:
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
This test has to be done with the Enterprise Edition template set up in your Maven.
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 (or a similar) 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.
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: