Maven Repositories: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(55 intermediate revisions by the same user not shown)
Line 9: Line 9:
=Overview=
=Overview=


A repository is used to hold build artifacts and dependencies of varying types. There are only two types of repositories: local and remote.  
A repository is used to hold build artifacts, dependencies of various types and plugins. There are only two types of repositories: local and remote.  


A local repository is a cache of the remote downloads and also contains temporary build artifacts.
A [[#The_Local_Repository|local repository]] is a cache of the remote downloads and also contains temporary build artifacts.


A remote repository is accessed over a network protocol such as http:// or even file://. They may be set up by other organizations, or by your own organization in order to share artifacts between different development teams.
A [[#Remote_Repositories|remote repository]] is accessible over the network.
 
=Where are Repositories Declared?=
 
==<span id="local_repository"></span>The Local Repository==
 
The local repository is a cache of the remote downloads and also contains temporary build artifacts. If a local repository location is defined in a [[Maven_settings.xml#.3ClocalRepository.3E|settings.xml]] file as [[Maven_settings.xml#.3ClocalRepository.3E|<localRepository>]], this location will be used. The <tt>settings.xml</tt> in <tt>$HOME/.m2</tt> takes precedence over the <tt>settings.xml</tt> in <tt>$M2_HOME/conf</tt>. If no <tt>settings.xml</tt> is available, the default location is <tt>$HOME/.m2/repository</tt>.
 
==<span id="remote_repository"></span>Remote Repositories==
 
A remote repository is accessed over a network protocol such as http:// or even file://. They may be set up by other organizations, or by your own organization in order to share artifacts between different development teams. If a dependency is not available in the local repository, Maven attempts to find it in a remote repository and cache it locally if found. The right place to declare additional repositories is, according to the Maven orthodoxy, the [[Maven settings.xml|settings.xml]] file. Repositories can also be declared in [[Maven pom.xml|pom.xml]], but usually that type of information does not belong in there.
 
The default Maven repository is https://repo.maven.apache.org/maven2/.


=Adding a Remote Repository=
=Adding a Remote Repository=
Line 25: Line 37:
<repositories>
<repositories>
     <repository>
     <repository>
         <id>my-internal-site</id>
         <id>my-site</id>
         <url>http://myserver/repo</url>
         <url>http://myserver/repo/</url>
     </repository>
     </repository>
</repositories>
</repositories>
Line 44: Line 56:
...
...
</pre>
</pre>
=Password-Protected Repositories=
{{External|https://maven.apache.org/guides/mini/guide-encryption.html}}
In case the remote repository is password protected, the authentication configuration is mapped to Maven configuration as follows:
1. In case this is the first password-protected repository configured for this Maven installation, and no master password was configured, set the master password.
Execute:
mvn --encrypt-master-password
and place the result (which is similar to {tiJTx7Yed80HP6UZZShSFgNMhqfl3Xcaz5S8ewCRbiI=}) in [[Maven settings-security.xml|settings-security.xml]]. For more details about settings-security.xml syntax and how to configure the master password, see: {{Internal|Maven settings-security.xml|settings-security.xml}}
2. Encrypt the password as follows and store the encrypted value to use at the next step:
mvn --encrypt-password [''password-in-clear'']
Providing the password on command line is optional, for added security do not, and wait for the command line utility to request it.
{{Warn|Successive executions of mvn --encrypt-password produces different results, and that is OK, any of the results can be used.}}
For more details about encrypting passwords and the master password, see:
{{Internal|Maven_Command_Line_Options#-ep.2C_--encrypt-password|mvn --encrypt-password}}
3. Declare a <server> in the <servers> section of the relevant file, which may be [[Maven_settings.xml#.3Cservers.3E|settings.xml]] or [[Maven_pom.xml#.3Cservers.3E|pom.xml]]. The most common - and recommended - option is to declare all this in a [[Maven Profile|profile]] in [[Maven_settings.xml|settings.xml]].
<servers>
    <server>
        '''<id>myServer</id>'''
        <username>my_username</username>
        <password>{...=}</password>
        ...
    </server>
</servers>
{{Error|This syntax did not actually work for Maven 3.5.2. Debugging with a [[Charles|proxy]] has shown that no "Authorization: " header is sent, even if the username/password was correctly set in configuration. The workaround was to write the headers directly, as described here: "[[Maven_settings.xml#Authenticating_by_Writing_Headers|settings.xml - Authenticating by Writing Headers]]".}}
More details about <servers> in: {{Internal|Maven_settings.xml#.3Cservers.3E|settings.xml <servers>}}
4. Use the server's id, such declared, in the repository declaration:
<repositories>
    <repository>
        '''<id>myServer</id>'''
        <name>My Protected Repository</name>
        ...
      </repository>
  </repositories>
5. Testing
The authentication can be tested by declaring a dependency from the newly configured repository in the pom.xml file and making sure it is pulled.
=Elements=
==<id>==
==<name>==
==<url>==
==<layout>==
"default" or "legacy".
==<releases>/<snapshots>==
Contains the policy for releases or snapshots.
<releases>|<snapshots>
    <enabled>true|false</enabled>
    <updatePolicy>always</updatePolicy>
    <checksumPolicy>warn</checksumPolicy>
</releases>>|<snapshots>
For more details on snapshots, see: {{Internal|Maven_Concepts#Stable_Versions_and_Snapshots|Stable Versions and Snapshots}}
===<enabled>===
true or false whether this repository is enabled for the respective type of artifact.
{{Warn|Setting <releases><enabled> to "false" for a repository effectively removes it from the list of repositories queried for released dependencies, even it the repository is an active profile.}}
===<updatePolicy>===
Specifies how often updates should attempt to occur. Maven will compare the local POM's timestamp, as stored in a repository's maven-metadata file, to the remote. The choices are: "always", "daily", "interval:X" where X is an integer in minutes or "never".
For more details on snapshots, see: {{Internal|Maven_Concepts#Stable_Versions_and_Snapshots|Stable Versions and Snapshots}}
===<checksumPolicy>===
When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options are to ignore , fail , or warn on missing or incorrect checksums.
=Using Maven Repositories when Compiling JBoss EAP=
Note that in some cases, multiple maven repositories are required, as with JDG 7 which relies on EAP 7:
<pre>
...
<profiles>
    <profile>
        <id>jdg7</id>
        <repositories>
            <repository>
                <id>jboss-eap-7.0.0.GA-maven</id>
                <url>file:///Users/ovidiu/runtime/jboss-eap-7.0.0.GA-maven-repository/maven-repository</url>
            </repository>
            <repository>
                <id>jboss-datagrid-7.0-maven</id>
                <url>file:///Users/ovidiu/runtime/jboss-datagrid-7.0.0-maven-repository/maven-repository</url>
            </repository>
        </repositories>
        ...
    </profile>
</profiles>
...
</pre>
A full example on how to configure that is available here:
<blockquote style="background-color: AliceBlue; border: solid thin LightSteelBlue;">
:https://github.com/NovaOrdis/playground/blob/master/jboss/infinispan/hotrod-client/pom.xml<br>
</blockquote>

Latest revision as of 20:22, 1 September 2020

External

Internal

Overview

A repository is used to hold build artifacts, dependencies of various types and plugins. There are only two types of repositories: local and remote.

A local repository is a cache of the remote downloads and also contains temporary build artifacts.

A remote repository is accessible over the network.

Where are Repositories Declared?

The Local Repository

The local repository is a cache of the remote downloads and also contains temporary build artifacts. If a local repository location is defined in a settings.xml file as <localRepository>, this location will be used. The settings.xml in $HOME/.m2 takes precedence over the settings.xml in $M2_HOME/conf. If no settings.xml is available, the default location is $HOME/.m2/repository.

Remote Repositories

A remote repository is accessed over a network protocol such as http:// or even file://. They may be set up by other organizations, or by your own organization in order to share artifacts between different development teams. If a dependency is not available in the local repository, Maven attempts to find it in a remote repository and cache it locally if found. The right place to declare additional repositories is, according to the Maven orthodoxy, the settings.xml file. Repositories can also be declared in pom.xml, but usually that type of information does not belong in there.

The default Maven repository is https://repo.maven.apache.org/maven2/.

Adding a Remote Repository

Both "http://" and "file://" work.

A generic http repository:

...
<repositories>
    <repository>
        <id>my-site</id>
        <url>http://myserver/repo/</url>
    </repository>
</repositories>
...

This is an example of adding a local EAP repository:

...
<repositories>
    <repository>
        <id>jboss-datagrid-6.6.0-maven-repository</id>
        <url>file:///Users/ovidiu/runtime/jboss-datagrid-6.6.0-maven-repository</url>
    </repository>
</repositories>
...

Password-Protected Repositories

https://maven.apache.org/guides/mini/guide-encryption.html

In case the remote repository is password protected, the authentication configuration is mapped to Maven configuration as follows:

1. In case this is the first password-protected repository configured for this Maven installation, and no master password was configured, set the master password.

Execute:

mvn --encrypt-master-password 

and place the result (which is similar to {tiJTx7Yed80HP6UZZShSFgNMhqfl3Xcaz5S8ewCRbiI=}) in settings-security.xml. For more details about settings-security.xml syntax and how to configure the master password, see:

settings-security.xml

2. Encrypt the password as follows and store the encrypted value to use at the next step:

mvn --encrypt-password [password-in-clear]

Providing the password on command line is optional, for added security do not, and wait for the command line utility to request it.


Successive executions of mvn --encrypt-password produces different results, and that is OK, any of the results can be used.

For more details about encrypting passwords and the master password, see:

mvn --encrypt-password

3. Declare a <server> in the <servers> section of the relevant file, which may be settings.xml or pom.xml. The most common - and recommended - option is to declare all this in a profile in settings.xml.

<servers>
   <server>
       <id>myServer</id>
       <username>my_username</username>
       <password>{...=}</password>
       ...
   </server>
</servers>

This syntax did not actually work for Maven 3.5.2. Debugging with a proxy has shown that no "Authorization: " header is sent, even if the username/password was correctly set in configuration. The workaround was to write the headers directly, as described here: "settings.xml - Authenticating by Writing Headers".

More details about <servers> in:

settings.xml <servers>

4. Use the server's id, such declared, in the repository declaration:

<repositories>
    <repository>
        <id>myServer</id>
        <name>My Protected Repository</name>
        ...
     </repository>
 </repositories>

5. Testing

The authentication can be tested by declaring a dependency from the newly configured repository in the pom.xml file and making sure it is pulled.

Elements

<id>

<name>

<url>

<layout>

"default" or "legacy".

<releases>/<snapshots>

Contains the policy for releases or snapshots.

<releases>|<snapshots>
    <enabled>true|false</enabled>
    <updatePolicy>always</updatePolicy>
    <checksumPolicy>warn</checksumPolicy>
</releases>>|<snapshots>

For more details on snapshots, see:

Stable Versions and Snapshots

<enabled>

true or false whether this repository is enabled for the respective type of artifact.


Setting <releases><enabled> to "false" for a repository effectively removes it from the list of repositories queried for released dependencies, even it the repository is an active profile.

<updatePolicy>

Specifies how often updates should attempt to occur. Maven will compare the local POM's timestamp, as stored in a repository's maven-metadata file, to the remote. The choices are: "always", "daily", "interval:X" where X is an integer in minutes or "never".

For more details on snapshots, see:

Stable Versions and Snapshots

<checksumPolicy>

When Maven deploys files to the repository, it also deploys corresponding checksum files. Your options are to ignore , fail , or warn on missing or incorrect checksums.

Using Maven Repositories when Compiling JBoss EAP

Note that in some cases, multiple maven repositories are required, as with JDG 7 which relies on EAP 7:

...
<profiles>
    <profile>
        <id>jdg7</id>
        <repositories>
            <repository>
                <id>jboss-eap-7.0.0.GA-maven</id>
                <url>file:///Users/ovidiu/runtime/jboss-eap-7.0.0.GA-maven-repository/maven-repository</url>
            </repository>
            <repository>
                <id>jboss-datagrid-7.0-maven</id>
                <url>file:///Users/ovidiu/runtime/jboss-datagrid-7.0.0-maven-repository/maven-repository</url>
             </repository>
        </repositories>
        ...
    </profile>
</profiles>
...

A full example on how to configure that is available here:

https://github.com/NovaOrdis/playground/blob/master/jboss/infinispan/hotrod-client/pom.xml