Lesson 2: Proxy and Hosted Maven Repositories



This lesson shows you how to create and populate proxy and hosted repositories in the Maven format. These are required to create a group repository, which is covered in lesson three.


Learning Objectives

 

By the end of this thirty minute lesson, you will be able to do the following with Nexus Repository Manager:

  • Gain general knowledge of Maven and the Central repository, and be able to install and configure Maven.
  • Understand the need for proxy repositories and how to create and populate a caching proxy repository in the Maven format.
  • Understand the need for hosted repositories and create maven-snapshots and maven-releases hosted repositories.

In This Lesson

Prerequisites

You have completed lesson one and Nexus Repository Manager 3 (NXRM3) is running.

What is Maven?

 

Apache Maven (Maven) is a software project management tool that serves as the centralized location for your project's builds, reporting, and documentation. Maven relies on the Central Repository — a public repository for Java components.

The Central Repository houses components that are also known as “artifacts” in the Maven world. These can be anything that are produced or used by your project including JARs, source and binary distributions, and WARs. Each of these Maven components are uniquely identified by a group ID, artifact ID, and version.

When you download and install Maven without any customization, it retrieves components from the Central Repository. When you configure a proxy to the Central Repository, Nexus Repository Manager retrieves and caches those same components for use across your teams. This lets you efficiently source, store, share, and deploy software components without relying on direct download from Maven Central, repeated downloads, or manual distribution.

Get Maven

Before configuring Maven proxy and hosted repositories, you need to get up and running with Maven. We’re not going to rewrite the wheel in this lesson, so we suggest going through Maven’s steps in Download and Install to get started.

If you have Homebrew installed, you can install Maven with the brew formula brew install maven. For more information, see http://brewformulas.org/Maven.

After downloading and installing Maven, test to verify the installation by running mvn -v in your terminal. This will show you the Maven version that’s installed.

Maven Proxy Repository

 

In the Repository Manager Basics module, you learned about the three repository types available in NXRM3—proxy, hosted, and group. In this lesson, we’re going to build on that knowledge using Maven as our example repository format.

A proxy repository is a repository that is linked to a remote repository, such as the Central Repository. When using a proxy, requests for components are verified against the cached components in your proxy repository. When you search for components, if the request isn’t found in your proxy repository, it is forwarded to the Central Repository. That component is then retrieved from Central and cached in the repository manager. If you search for that same component again, it will be found in local storage. This eliminates the need to go to the Central Repository and reduces bandwidth and time needed to retrieve the components you need.

When components are stored in a Nexus Repository Manager proxy, a copy of those components stays there indefinitely. In the event a component becomes unavailable in the Central Repository, you’ll still have access to it in your proxy. This provides more control over the components you need to build your applications.

Nexus Repository Manager ships out-of-the-box with a Maven-central proxy repository already configured to accesses the Central Repository. Even though there’s already a Maven Central proxy setup, for the purposes of this lesson, we’re going to make a new proxy repository, as described in the next section.

Try it Out: Maven Proxy Repository Configuration

 

In the following exercise, we’ll show you how to configure Maven to check your Nexus Repository Manager, make a test project, and then create and populate a Maven proxy repository.

Nexus Repository Manager Maven Configuration

To use repository manager with Apache Maven, you need to first configure Maven to check the repository manager instead of the default, built-in connection to the Central Repository. To do this, add a mirror configuration and override the default configuration for the central repository in your ~/.m2/settings.xml as shown below. For more information on Maven settings, see https://maven.apache.org/settings.html.

If you haven’t run mvn install, the ~.m2 repo may not have been created. If you don’t see this repo, run mkdir .m2 and then add the settings.xml manually.

<settings>
  <mirrors>
    <mirror>
      <!--This sends everything else to /public -->
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://localhost:8081/repository/maven-proxy-test/</url>
    </mirror>
  </mirrors>
  <profiles>
    <profile>
      <id>nexus</id>
      <!--Enable snapshots for the built in central repo to direct -->
      <!--all requests to nexus via the mirror -->
      <repositories>
        <repository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
     <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <!--make the profile active all the time -->
    <activeProfile>nexus</activeProfile>
  </activeProfiles>
</settings>

Make a Maven Project

In this section, we’ll create a Maven project also known as a Project Object Model or POM. We’ll use this POM later to cache new components from Maven Central to your proxy repository.

  1. From the command-line interface, make a new directory for your Maven project in the location of your choice. For example navigate to your user directory and then use the command mkdir maven-test.
  2. Open your new directory with cd maven-test.
  3. Next, create a POM file (pom.xml) with the command touch pom.xml.
  4. And open the file with open pom.xml.

    This opens the POM in the default application. If you want to open in a different app, use -a <application name>. For example, open pom.xml -a textedit.

  5. Populate your POM with the values below:

    <project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>nexus-proxy</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
    <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.10</version>
    </dependency>
    </dependencies>
    </project>
  6. Save the file.

Create a Maven Proxy Repository

Next up, we’ll create a new Maven proxy in the Nexus Repository Manager UI.

  1. Open the Nexus Repository Manager user interface.
  2. Click Administration in the top navigation menu, and then select Repositories.
  3. Click Create repository, and then choose the maven2 (proxy) recipe from the list.
  4. Add the following text in the required fields:
    1. Name: maven-proxy-test
    2. Remote storage URL: https://repo1.maven.org/maven2
  5. Click Create repository to complete the form.

The repository manager is now configured to proxy Maven Central.

Cache New Components from Maven Central to the Proxy

The last step is to build our Maven project and then view the components in our proxy repository.

  1. In your terminal, navigate to the POM file you created, and run the build with the command mvn package. Your build is ready when you see a “BUILD SUCCESS” message.
  2. In Nexus Repository Manager, click Browse  in the main toolbar and then select Browse from the left-side menu.
  3. Of your repositories, choose maven-proxy-test. You'll see the test components you proxied for the Maven format during the previous steps.
  4. Click on a component name to review its details.

You may need to refresh Nexus Repository Manager to see the list of proxied components.

If you get a failure when running mvn package, you can try forcing a Maven update with mvn package -U.

Exercise Summary

So...what did we just do? We set up a mirror configuration in your Maven settings file to check the repository manager and then made your Maven project or POM. We then created a new Maven proxy repository in the Repository Manager UI, packaged your Maven project, and then went back to NXRM to view the components in your proxy repository.

Up next, we’re going to go over a second repository type: hosted repositories.

Maven Hosted Repositories

 

In the previous section, you learned how to set up a proxy repository to Maven Central and use that to cache components from the public repo. This is hugely beneficial and saves time, but what do you do with internal components that aren’t downloaded from a public repository, but are used by various development teams in your organization? You make a hosted repository to act as the authoritative location for your in-house components.

Back in the first module, you learned that the default installation of Nexus Repository Manager includes two hosted Maven repositories. The maven-releases repository uses a release version policy and the maven-snapshots repository uses a snapshot version policy.

Release repositories are intended to be the place where your organization publishes internal releases. A release component is a component created by a specific, versioned release. These components are considered to be solid, stable and perpetual to guarantee the builds that use them are repeatable over time. You can also use this repository for third-party components that are not available in external repositories and can’t be retrieved using a configured proxy repository.

Snapshot components change over time and are generated during active development of a software project. Continuous development is typically performed with snapshot versions supported by the Snapshot version policy. These version values have to end with -SNAPSHOT in the POM file. This allows repeated uploads where the actual number used is composed of a date/timestamp and an enumerator and the retrieval can still use the -SNAPSHOT version string.

Much like a production environment and a staging environment, we recommend using the release repository for stable components in production and a snapshot repository for components still in the development phase.

Try it out: Maven Hosted Repositories Configuration

 

There are a couple steps to perform before using Maven hosted repositories — (1) add server settings to your Maven config file and then (2) configure the POM for linking your projects to maven-snapshots and maven-releases hosted repos. When these are done, you can go ahead and deploy your snapshot and release builds and then view the components in your hosted repositories.

Update Settings.xml

The first step is to add credentials for deployment. This example uses nexus as the ID along with the default username and password.

Navigate back to your ~/.m2/settings.xml and add the following server configuration to settings.xml:

<servers>
<server>
<id>nexus</id>
<username>admin</username>
<password>admin123</password>
</server>
</servers>

Update the POM

Next, we need to configure deployment in our project. For both the snapshots and releases repositories, we’ll deploy to the out-of-the-box repos already in NXRM. Deployment to a repository is configured in the pom.xml for the respective project in the distributionManagement section.

Open your POM and add the following section:

<project>
...
<distributionManagement>
<repository>
<id>nexus</id>
<name>maven-releases</name>
<url>http://localhost:8081/repository/maven-releases/</url>
</repository>
<snapshotRepository>
<id>nexus</id>
<name>maven-snapshots</name>
<url>http://localhost:8081/repository/maven-snapshots/</url>
</snapshotRepository>
</distributionManagement>


And then save the POM.

Setup is now complete, so next we’ll run the builds and view our hosted components in the Nexus Repository Manager UI.

Run Snapshots Build

  1. In your terminal, navigate to your POM, and run the build with mvn clean deploy. Your build is ready when you see a “BUILD SUCCESS” message.
  2. In Nexus Repository Manager, click Browse  in the main toolbar and then select Browse from the left-side menu.
  3. Of your repositories, choose maven-snapshots. You'll see the test components from your Maven Snapshots build.
  4. Click on a component name to review its details:

Run Releases Build

  1. When ready for release, remove “SNAPSHOTS” from the version tag in your pom:
    <version>1.0-SNAPSHOT</version>
  2. Save your POM.
  3. In your terminal, navigate to your POM, and run the build with mvn clean deploy. Your build is ready when you see a “BUILD SUCCESS” message.
  4. In Nexus Repository Manager, click Browse  in the main toolbar and then select Browse from the left-side menu.
  5. Of your repositories, choose maven-releases. You'll see the test components from your Maven Releases build.
  6. Click on a component name to review its details:

Exercise Summary

So...what did we just do? We added server settings to the settings.xml file in our .m2 folder. We also mapped maven-releases and maven-snapshots to our project by adding a Distribution Management section to the POM.

We then ran a snapshots build with mvn clean deploy and verified the snapshots hosted repo was populated in the UI.

Finally, we removed the snapshots tag from our POM and then ran mvn clean deploy again to get the release repo.

Activity: Test Your Knowledge

  1. What is the Central Repository?
    1. The middle of a storage facility.
    2. The public repository used for Maven components.
    3. A Java library.

  2. What is the purpose of adding a Maven proxy repository in Nexus Repository Manager?
    1. To link a remote repository where requests for components are verified against the cached components in your proxy repository.
    2. To store local and third-party components used across the organization.
    3. To be the principal storage location for all components.

  3. What is the purpose of adding a Maven hosted repository in Nexus Repository Manager?
    1. To cache components from the Central Repository.
    2. It’s the hospitable thing to do.
    3. To create a place for internal components that aren’t downloaded from a public repository, but are used by your development teams.


  1. B - The public repository used for Maven Components
  2. A - To link a remote repository where requests for components are verified against the cached components in your proxy repository.
  3. C - To create a place for internal components that aren’t downloaded from a public repository, but are used by your development teams.



You have now successfully created and populated proxy and hosted Maven repositories. 


Up next, you'll learn how to create a repository group and view the components in lesson 3.


← Lesson 1
Lesson 3 →