Maven is a tool for managing project dependencies and building your Magnolia project.
This page describes how to configure Maven to download Magnolia modules and webapps from our Nexus server, with appropriate access credentials.
Install Maven
Download and Install Maven. In order to verify Maven has been installed correctly:
- Open a terminal or a shell.
- Issue the command
mvn -v
. The command should produce an output similar to this:
mvn -v Apache Maven 3.9.1 (2e178502fcdbffc201671fb2537d0cb4b4cc58f8) Maven home: /usr/local/apache-maven-3.9.1 Java version: 17.0.6, vendor: Eclipse Adoptium, runtime: path/to/install Default locale: fr_FR, platform encoding: UTF-8 OS name: "<OPERATING_SYSTEM>"
Maven keeps your user configuration and local repository under the
${user.home}/.m2/
directory. See also Configuring Maven.
Set up Magnolia repositories
For DX Core projects, or for community releases in maintenance mode, add the following repository to your project POM (or Maven settings profile), and follow the next sections to set up authentication:
<repositories> <repository> <id>magnolia.nexus.enterprise</id> <url>https://nexus.magnolia-cms.com/repository/enterprise</url> </repository> </repositories>
For Community Edition projects, simply use the repositories below:
<repositories> <repository> <id>magnolia.nexus.public</id> <url>https://nexus.magnolia-cms.com/repository/public</url> </repository> <repository> <id>vaadin-addons</id> <url>https://maven.vaadin.com/vaadin-addons/</url> </repository> </repositories>
See also: Maven – Setting up Multiple Repositories
Create a master password (recommended)
Run the following command:
mvn --encrypt-master-password
This command will produce an encrypted version of the password, something like
{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}
Store this password in your ~/.m2/settings-security.xml
; it should look like
<settingsSecurity> <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master> </settingsSecurity>
See more: Maven – Password Encryption
Set up credentials in Maven settings
Log into Nexus with your regular credentials. Go to your Profile from the user menu, then select User Token in the drop-down.
See more: Security Setup with User Tokens
If you have created a master password above, run the following command with your user token pass code.
mvn --encrypt-password {userTokenPassCode}
You will use the encrypted pass code in the <server>
credentials below, instead of your {userTokenPassCode}
in clear text.
Add the following to your Maven settings at ~/.m2/settings.xml
, with your Nexus user tokens obtained above:
<servers> <server> <!-- must match the repository id in your project pom --> <id>magnolia.nexus.enterprise</id> <username>{userTokenNameCode}</username> <password>{userTokenPassCode}</password> </server> </servers>
The server id must match the repository id in your project pom or 'magnolia-repositories' profile in maven settings.
Using Magnolia Maven archetypes
In order to use Magnolia Maven archetypes, add the following to your Maven settings:
<profiles> <profile> <id>magnolia-repositories</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <!-- required for Magnolia Maven archetypes --> <repository> <id>magnolia.nexus.public</id> <url>https://nexus.magnolia-cms.com/repository/public</url> </repository> </repositories> </profile> </profiles>
See also: Maven Archetype Plugin — Archetype repository
Download Magnolia Maven settings (advanced)
For deploying and releasing purposes, mostly for Magnolia staff, a download script and template is available in the 'onboarding' repository on Bitbucket.
Mirroring
If you have your own Repository Manager, below are the repositories you can mirror:
12 Comments
Pete Ryland
Please note that nexus should be accessed via https only due to man in the middle attacks. Http access will shortly be switched off.
Razvan
Is / will there be a similar setup tutorial for Gradle?
Christoph Meier
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.
Christopher Chard
Hey guys,
I am having trouble downloading from Nexus. After the username / pw prompt I get this:
I tried this:
Nothing works. Please help!
Thank you!
Cheers
Chris
Christoph Meier
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
Bradley Andersen
example project
documentation-check-maven-settings
DNESebastian Klingberg
Hi Bradley Andersen, if you created the Maven Check Project, can you please make it available again or fix the documentation Thanks!
https://git.magnolia-cms.com/projects/DOCUMENTATION does not include the `documentation-check-maven-settings` project (or it's an permission issue on my side)
EDIT
Seems that the project is available here: https://git.magnolia-cms.com/users/cmeier/repos/documentation-check-maven-settings/browse (You maybe need to ask Christoph Meierfor permission )
Christoph Meier
Well, https://git.magnolia-cms.com/users/cmeier/repos/documentation-check-maven-settings is a fork of the original repo which was in DOCUMENTATION but which has been deleted.
I can give read access to Sebastian. I even can enable
But at the end it's still "my" git-repo. We probably should add that "check-repo" to another place, since I cannot guarantee that my fork will remain there forever.
Martin Drápela - maybe we cam bring it back to its original location?
P.S.: I have granted you read&write access to my repo
Christoph Meier
Read access granted to Sebastian Klingberg ✅
Christoph Meier
F.Y.I.
I have just raised magnolia-version (6.2.17) and java-version (1.8).
Daniel Alonso
Hi everybody!
I have faced some problems during my local builds with maven and java 11 (java 11.0.2).
To be more precised, I had the following problems:
Peer not authenticated error
Fixed by using:
-Dmaven.wagon.http.ssl.insecure=true -Dmaven.wagon.http.ssl.allowall=true
And
No PSK available. Unable to resume
For this, you cant upgrade to java 11 greater than 11.0.2 or use the following jvm params:
-Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2
Sources:
https://blog.neodoo.es/2014/01/22/peer-not-authenticated-en-maven/
https://stackoverflow.com/questions/52574050/javax-net-ssl-sslexception-no-psk-available-unable-to-resume
Mikaël Geljić
Thanks! That one is quite an oldie yeah; more recent JDKs are definitely fine. Any reason you got 11.0.2 specifically? It seems jdk-11.0.17+8 is the latest, via Eclipse Temurin (formerly AdoptOpenJDK).