Working with Nexus Repository

Overview

Most modern software project management tools promote the idea of utilizing a centralized repository environment to store and provide software dependencies on an as needed basis.  An example of this is the popular Maven central repository (http://repo1.maven.org/maven/). Open to all and hosted by the Apache software foundation, Maven central is the default location where one would pull dependencies (i.e. software artifacts) from when creating a Maven based software project.  For many organizations looking to utilize Maven as a tool for managing software projects a remotely located, public “open to all” software repository is problematic in terms of a security risk as well as Internet bandwidth utilization.  The alternative approach is for the organization to host its own repository.  Recently I went through the process of standing up a Sonatype Nexus OSS Repository for an organization. This blog entry documents an overview of the installation, configuration and management tips, as well as information pertaining to the development environments that interface with the repository.

 Pre-requisites

The Sonatypes Nexus OSS install located at http://www.sonatype.org/nexus
Nexus requires a Java 7 compliant JVM

Installing Nexus Repo

By default Nexus will install it own instance of Jetty and run on port 8081. If desired there is an option to install Nexus into a  different J2EE container.  To install Nexus unzip/untar to the location where Nexus will be run out of.  A recommendation (although NOT required) from the Nexus Installation guide is to define a “NEXUS_HOME” System variable pertaining to this location.

To start the server run the following command

$NEXUS_HOME/bin/nexus start

 Key points related to installation

$NEXUS_HOME/conf/nexus.properties
  • contains configuration details for the nexus server instance
  • port the app runs on
  • web application context
  • location of repo
$NEXUS_HOME/bin/jsw/conf/wrapper.conf If $JAVA_HOME is NOT JVM7 compliant starting nexus fails with the following message

wrapper  | Starting the nexus service...
wrapper  | The nexus service was launched, but failed to start.

To fix this edit the property “wrapper.java.command” with the fully pathed location of a valid JVM7 in the wrapper.conf file

$NEXUS_HOME/logs default location of logs

Administering Nexus Repository

Typical administration of the Repository is done via a Web Interface.  For the purpose of this blog entry I will refer to the The Nexus repository location as  http://localhost:8081/nexus.   Administrative duties require the user to be authenticated as an administrative user. The default username/password for the Nexus repository is

Username: admin
Password: admin123

Key Repositories

The following repository setup is what we used as an initial implementation of the organizations Nexus setup, this is a learning process so its usage may be a little immature. One will note the lack of release and snapshot repositories. Once the CI environment and Repository have been made to work together the expectation is to reintroduce the release/snapshot concept.

Central My understanding of the intent for “Central” repository is to function as a proxy for the publicly available Maven “central”. Their is not an option to upload an artifact into the Nexus “Central”.  This location should be treated as merely a holding place for elements downloaded from the public central as a means to save bandwidth. Manually copying files in and out of central is an option but that doesn’t seem like the right approach. At this time we are debating how to utilize this repository, the current thought process is this will not be used.
Project Repositories Each individual project will have its own repository. The exact sub-division between projects and groups is in the process of being worked out.
Approved third party libraries Open and closed source artifacts available to internal projects. This repository is also available via a repository group.
Organizations common libraries Artifacts and archetypes built in house and utilized by multiple projects. This along with the “Approved third party libraries” repository make up the organization’s repository group.

Updating the repository

Adding files through the Nexus Administrative interface
  1. Access http://localhost:8081/nexus, login as an admin user (admin/admin123)
  2. Select the unique repository
  3. Navigate to “Artifact Upload” tab
  4. Use the form to upload the specific file; complete group, artifact, and version details

Maven deploy goal

Example using Maven deploy goal from command line

mvn deploy:deploy-file -DgroupId=junit -DartifactId=junit 
-Dversion=4.8.1  -Dpackaging=jar 
-Dfile=c:\temp\junit-4.8.1.jar 
-DrepositoryId=nexus-repo 
 -Durl=http://localhost:8081/nexus/content/repositories/thirdparty

In this example the “nexus-repo” reference would need to exist as a server entry in maven’s settings.xml file.  Additionally the deploy goal can be implemented via a project pom.xml, see the examples later in this blog entry for how to setup Maven to work the deploy goal.

More documentation regarding the Maven deploy goal
https://maven.apache.org/plugins/maven-deploy-plugin/
https://maven.apache.org/guides/mini/guide-3rd-party-jars-remote.html

Bulk uploading

Although not a recommended long term solution, manually copying folders and files into the location where the repository files are stored on the server is an option. Testing found, if artifacts are copied in the proper format Nexus will update its own index’s. This allows for an individual to build a repository on another machine and copy it into the location.  A typical Local Maven repository (commonly located at  %WINDOWS_USER %/.m2/repository) and the content of another Nexus Repository have been tested to work for the copy.

Proxy to fetch public resources

Devising a strategy to utilize Nexus’s proxy capabilities to fetch publicly available libraries is also an option. For individuals behind a corporate proxy, proxy settings can be configured under the Administration->Server section of the Nexus Admin screen.

Developer Setup

Connecting to the Nexus Repository can be implemented in a number of ways.  Specific Repositories could be referenced in a unique project’s pom.xml file and/or options could be configured on the individual’s local Maven installation in their settings.xml file. This section describes the various settings and recommended approaches to connecting from a developer machine to a Nexus repository.

settings.xml and pom.xml
  • settings.xml is a configuration file common to an entire Maven installation, by default it is located at $MAVEN_HOME/conf/settings.xml or $WINDOWS_USER/.m2/settings.xml changes applied to this file affect all projects run by maven.

  • pom.xml is a unique projects control file for Maven, it is located at the root of every Maven project and sub-project. settings in this file apply only to the unique project (and sub-projects).

Pointing Maven to “Central” repo

Add a mirror entry under the mirrors node of settings.xml to utilize the “central” repository located at http://localhost:8081/nexus/content/repositories/central/

<mirror>
 <id>nexus</id>
 <url>http://localhost:8081/nexus/content/repositories/central</url>
 <mirrorOf>central</mirrorOf>
</mirror>
Configuring Maven to authenticate to Nexus Repository for Deployment goal

In order to deploy artifacts to a Nexus Repository the local Maven installation must be able to provide the proper details in order to authenticate with the server. Recommended way to do this is to add a server entry under the servers section in settings.xml.

<server>
 <id>nexus-repo</id>
 <username>admin</username>
 <password>admin123</password> 
</server>

Once this is configured, Mavens deploy goal can reference this via the command line argument to deploy an artifact to the repository, see the example from document.

-DrepositoryId=nexus-repo

In a project pom.xml file the “distributionManagement” XML entry is used references the server entry in settings.xml. When Maven’s deploy goal is called it will utilize these settings.

<distributionManagement>
 <repository>
 <id>nexus-repo</id>
 <url>http://localhost:8081/nexus/content/repositories/org-archetypes</url>
 </repository>
</distributionManagement>
Configure Maven to utilize public repositories

Although not recommended in the specific case I am working on there will most likely be times when an individual is behind a corporate proxy server and requires access to pull artifacts from publicly available repositories.  A use case for this may be during the start of a new project when the correct libraries for the task are being evaluated. To configure Maven to utilize a corporate network proxy servers edit settings.xml in the following manner.

  1. If it is set, remove references to “central” mirror
  2. Add an entry under the proxies XML node
<proxy>
 <active>true</active>
 <protocol>http</protocol>
 <username>${user.name}</username>
 <password>${network.password}</password>
 <host>${proxy.server}</host>
 <port>80</port>
 <nonProxyHosts>127.0.0.1|localhost|${local.nexus.repo}</nonProxyHosts>
</proxy>

 

Embedding repository details into a projects POM.XML

Add the following entry within the pom.xm of a project to utilize a unique repository for pulling artifacts.

<repositories>
 <repository>
 <id>heb-repo</id>
 <url>http://localhost:8081/nexus/content/repositories/heb-repo</url>
 </repository>
</repositories>