Recent Maven Blogs

16.1.1. History of Nexus

Tamas Cservenak started working on Proximity in December 2005 as he was trying to find a way to isolate his own systems from an incredibly slow ADSL connection provided by a Hungarian ISP. Proximity started as a simple web application to proxy artifacts for a small organization with connectivity issues. Creating a local on-demand cache for Maven artifacts from the central Maven repository gave an organization access to the artifacts on the Central Maven Repository, but it also made sure that these artifacts weren't downloaded over a very slow ADSL connection used by a number of developers. In 2007, Sonatype asked Tamas to help create a similar product named Nexus. Nexus is currently considered the logical next step to Proximity. Nexus currently has an active development team, and portions of the indexing code from Nexus are also being used in m2eclipse.

16.2.1. Downloading Nexus from Sonatype

You can find information about Nexus at http://nexus.sonatype.org. To download Nexus, go to http://nexus.sonatype.org/downloads/. Click on the download link an download the appropriate archive for your platform. Nexus is available as a ZIP and a Gzip'd TAR file.

16.2.2. Installing Nexus

Installing Nexus is straightforward, unpack the Nexus archive in a directory. If you are installing Nexus on a local workstation to give it a test run, you can install it in your home directory or whenever you like; Nexus doesn't have any hard coded directories, it will run from any directory. If you downloaded the ZIP archive, run:

$ unzip nexus-1.0.0-bundle.zip

And, if you download the GZip'd TAR archive, run:

$ tar xvzf nexus-1.0.0-bundle.tgz

If you are installing Nexus on a server, you might want to use a directory other than your home directory. On a Unix machine, this could be under /usr/local/nexus-1.0.0 with a symbolic link /usr/local/nexus to the nexus directory. Using a generic symbolic link nexus to a specific version is a common practice which makes it easier to upgrade when a newer version of Nexus is made available.

$ sudo cp nexus-1.0.0-bundle.tgz /usr/local
$ cd /usr/local
$ sudo tar xvzf nexus-1.0.0-bundle.tgz
$ ln -s nexus-1.0.0 nexus

Although it isn't required for Nexus to run, you may want to set an environment variable NEXUS_HOME in your environment which points to the installation directory of Nexus. This chapter will refer to this location as ${NEXUS_HOME}.

16.2.3. Running Nexus

When you start Nexus, you are starting a web server on the default port of localhost:8081. Nexus runs within a servlet container called Jetty and it is started with a native service wrapper called the Tanuki Java Service Wrapper. This service wrapper can be configured to run Nexus as a Windows service or a Unix daemon. To start Nexus, you will need to find the appropriate startup script for your platform. To see the list of available platforms, list the contents of the ${NEXUS_HOME}/bin/jsw directory.

The following example listing starts Nexus using the script for Mac OSX. First we list the contents of the ${NEXUS_HOME}/bin/jsw to show you the available platforms, then we make the contents of the bin directory executable with chmod. The Mac OSX wrapper is started with a call to app start, and then we tail the wrapper.log in ${NEXUS_HOME}/container/logs. Nexus will initialize itself and print a message that it is listening on localhost:8081.

$ cd Nexus
$ ls ./bin/jsw/
aix-ppc-32/          linux-ppc-64/        solaris-sparc-32/
aix-ppc-64/          linux-x86-32/        solaris-sparc-64/
hpux-parisc-32/      linux-x86-64/        solaris-x86-32/
hpux-parisc-64/      macosx-universal-32/ windows-x86-32/
$ chmod -R a+x bin
$ ./bin/jsw/macosx-universal-32/nexus start
Nexus Repository Manager...
$ tail -f container/logs/wrapper.log 
INFO  ... [ServletContainer:default] - SelectChannelConnector@0.0.0.0:8081

At this point, Nexus will be running and listening on port 8081. To use Nexus, fire up a web browser and type in the URL: http://localhost:8081/nexus. Click on the "Log In" link in the upper right-hand corner of the web page, and you should see the following login dialog.

THE DEFAULT NEXUS USERNAME AND PASSWORD IS "admin" AND "admin123".

Figure 16.1. Nexus Login Window (default login/password is admin/admin123)

16.2.4. Post-Install Checklist

Nexus ships with some default passwords and settings for repository indexing that need to be changed for your installation to be useful (and secure). After installing and running Nexus, you need to make sure that you complete the following tasks:

16.2.5. Startup Scripts for Linux

You can configure Nexus to start automatically, by copying the app script to the /etc/init.d directory. On a Linux system (tested with Redhat, Fedora, Ubuntu, or CentOS) perform the following operations as the root user:

At the end of this you should have a file in /etc/init.d/nexus which starts with a series of configuration properties which look something like this (assuming that you've installed Nexus in /usr/local/nexus and that you have Java installed in /usr/java/latest):

JAVA_HOME=/usr/java/latest
PATH=${PATH}:${JAVA_HOME}/bin
APP_NAME="nexus"
APP_LONG_NAME="Sonatype Nexus"
NEXUS_HOME=/usr/local/nexus
PLATFORM=linux-x86-64
WRAPPER_CMD="${NEXUS_HOME}/bin/jsw/${PLATFORM}/wrapper"
WRAPPER_CONF="${NEXUS_HOME}/conf/wrapper.conf"
PRIORITY=
PIDDIR="/var/run"
#RUN_AS_USER=nexus

16.2.5.1. Add Nexus as a Service on Redhat, Fedora, and CentOS

This script has the appropriate chkconfig directives, so all you need to do to add Nexus as a service is run the following commands:

$ cd /etc/init.d
$ chkconfig --add nexus
$ chkconfig --levels 345 nexus on
$ service nexus start
Starting Sonatype Nexus...
$ tail -f /usr/local/nexus/logs/wrapper.log

The second command adds nexus as a service to be started and stopped with the service command and managed by chkconfig command. chkconfig manages the symbolic links in /etc/rc[0-6].d which control the services which are started and stopped when the operating system restarts or transitions between run-levels. The third command adds nexus to run-levels 3, 4, and 5. The service command starts Nexus, and the last command tails the wrapper.log to verify that Nexus has been started successfully. If Nexus has started successfully you should see a message notifying you that Nexus is listening for HTTP connections on a port.

16.2.5.2. Add Nexus as a Service on Ubuntu

The process for setting Nexus up as a service on Ubuntu differs slightly from the process used on a Redhat variant. Instead of running chkconfig, you should run the following sequence of commands once you've configured the startup script in /etc/init.d:

$ cd /etc/init.d
$ update-rc.d nexus defaults
$ service nexus start
Starting Sonatype Nexus...
$ tail -f /usr/local/nexus/logs/wrapper.log

16.2.6. Running Nexus Behind a Proxy

This section is entirely optional. Nexus is based on Jetty which is a very high-performance servlet container based on Java NIO. From a performance perspective, there is no reason for you not to run Nexus by itself without a proxy. Yet, more often than not, organizations run applications behind a proxy for security concerns and to consolidate multiple disparate applications using tools like mod_rewrite and mod_proxy. For this reason, we've included some brief instructions for configuration mod_proxy in Apache HTTPd. We assume that you've already installed Apache 2, and that you are using a Virtual Host for www.somecompany.com.

Let's assume that you wanted to host Nexus behind Apache HTTPd at the URL http://www.somecompany.com. To do this, you'll need to change the context path that Nexus is served from.

At this point, edit the HTTPd configuration file for the www.somecompany.com virtual host. Include the following to expose Nexus via mod_proxy at http://www.somecompany.com/.

ProxyRequests Off 
ProxyPreserveHost On 

<VirtualHost *:80> 
  ServerName www.somecompany.com 
  ServerAdmin admin@somecompany.com 
  ProxyPass / http://localhost:8081/
  ProxyPassReverse / http://localhost:8081/
  ErrorLog logs/somecompany/nexus/error.log 
  CustomLog logs/somecompany/nexus/access.log common 
</VirtualHost>

Alternatively, if you just wanted to continue to serve Nexus at the /nexus context path, you would not change the contextPath in ${NEXUS_HOME}/conf/plexus.xml and you would include the context path in your ProxyPass and ProxyPassReverse directives as follows:

  ProxyPass /nexus/ http://localhost:8081/nexus/
  ProxyPassReverse /nexus/ http://localhost:8081/nexus/

Apache configuration is going to vary based on your own application's requirements and the way you intend to expose Nexus to the outside world. If you need more details about Apache HTTPd and mod_proxy, please see http://httpd.apache.org.

16.3.1. Browsing Repositories

One of the most straight-forward uses of the Nexus is to browse the structure of a Maven repository. If you click on the Browse Repositories menu item in the Views menu, you should see the following display. The top-half of Figure 16.3, “Browsing a Nexus Repository” shows you a list of groups and repositories along with the type of the repository and the repository status.

Figure 16.3. Browsing a Nexus Repository

When you are browsing a repository, you can right click on any file and download it directly to your browser. This allows you to retrieve specific artifacts manually, or examine a POM file in the browser.

16.3.2. Browsing Groups

Nexus contains ordered groups of repositories which allow you to expose a series of repositories through a single URL. More often than not, an organization is going to point Maven at the two default Nexus groups: Public Repositories and Public Snapshot Repositories. Most end-users of Nexus are not going to know what artifacts are being served from what specific repository, and they are going to want to be able to browse the Public Repository. To support this use case, Maven allows you to browse the contents of a Nexus Group as if it were a single merged repository with a tree structure. Figure 16.4, “Browsing a Nexus Group” shows the browsing interface with a Nexus Group selected for browsing. There is no difference to the user experience of browsing a Nexus Group vs. browsing a Nexus Repository.

Figure 16.4. Browsing a Nexus Group

16.3.3. Searching for Artifacts

In the left-hand navigation area, there is a Artifact Search text field next to a magnifying glass. To search for an artifact by groupId or artifactId, type in some text and click the magnifying glass. Typing in the the search term "maven" and clicking the magnifying glass should yield a search result similar to Figure 16.5, “Results of an Artifact Search for "maven"”.

Figure 16.5. Results of an Artifact Search for "maven"

Once you've located the artifact you were looking for you can click on the Download link to download the artifact. Nexus is going to show you 50 results at a time, and provide links on the bottom of the search result panel for you to navigate through the search results. If you would prefer to see a list of all of the matching artifacts, you can select Fetch All from the drop down at the bottom of the search result panel.

In addition to searching by a groupId or an artifactId, Nexus has a feature which allows you to search for an artifact by a checksum.

16.3.4. Browsing System Feeds

Nexus provides feeds that capture system events, you can browse these feeds by clicking on System Feeds under the View menu. Clicking on System Feeds will show the panel in Figure 16.6, “Browsing Nexus System Feeds”. You can use these simple interface to browse the most recent reports of artifact deployments, cached artifacts, broken artifacts, and storage changes that have occurred in Nexus.

Figure 16.6. Browsing Nexus System Feeds

These feeds can come in handy if you are working at a large organization with multiple development teams deploying to the same instance of Nexus. If such an arrangement, all developers in an organization can subscribe to the RSS feeds for New Deployed Artifacts as a way to ensure that everyone is aware when a new release has been pushed to Nexus. Exposing these system events as RSS feeds also opens to the door to other, more creative uses of this information, such as connecting Nexus to external automated testing systems. To access the RSS feeds for a specific feed, select the feed in the System Feeds view panel and then click on the Subscribe button. Nexus will then load the RSS feed in your browse and you can subscribe to the feed in your favorite RSS reader.

There are six system feeds available in the System Feeds view, and each has a URL which resembles the following URL:

http://localhost:8081/nexus/service/local/feeds/recentChanges

Where recentChanges would be replaced with the identifier of the feed you were attempting to read. Available system feeds include:

16.3.5. Browsing Log Files and Configuration

Logs and Config Files is only visible to Administrative users under the Views menu. Click on this option brings up the dialog shown in Figure 16.7, “Browsing Nexus Logs and Configuration”. From this screen you can view the following log and configuration files by clicking on the drop down selection next to the Download button.

Figure 16.7. Browsing Nexus Logs and Configuration

16.3.6. Changing Your Password

If you have the appropriate security privilege, you will see an option to change your password in the left-hand side of the browser. To change your password, click on change password, supply your current password, and choose a new password. When you click on Change Password, your Nexus password will be changed.

Figure 16.8. Changing Your Nexus Password

16.4.1. Using the Nexus Central Proxy Repository

To configure Maven to consult Nexus instead of the Central Maven repository, add the mirror settings from Example 16.1, “Configuring Maven Settings for Nexus (~/.m2/settings.xml)” to your ~/.m2/settings.xml file.

<?xml version="1.0"?>
<settings>
  ...
  <mirrors>
    <mirror>
      <id>Nexus</id>
      <name>Nexus Public Mirror</name>
      <url>http://localhost:8081/nexus/content/groups/public</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
  ...
</settings>

Once you've configured Nexus to be the mirror for all repositories, Maven will now consult the local installation of Nexus instead of going out to the central Maven repository. If Nexus has the artifact requested, the artifact will be served from the local Nexus installation. If Nexus does not have the artifact, Nexus will retrieve it from the remote repository and then add it to the local mirror of that remote repository.

To test how Nexus is working, try deleting a directory from your local Maven repository, and then running a Maven build. If you delete ~/.m2/repository/org, you'll be deleting a large number of dependencies (including Maven plugins). The next time you run Maven, you should see the following:

$ mvn clean install
...
Downloading: http://localhost:8081/nexus/content/groups/public/...
3K downloaded

This output should convince you that Maven is communicating with your local installation of Nexus instead of going out to the Central Maven repository to retrieve an artifact. After you've run a few builds against your local Nexus installation, you can then start to browse the contents cached in your local instance of Maven.

16.4.2. Using Nexus for Snapshot Repositories

The Maven Settings from Section 16.4.1, “Using the Nexus Central Proxy Repository” will allow you to use the Nexus public group which resolves artifacts from four repositories managed by Nexus, but it won't allow you to reference the public-snapshots group which includes the Apache and Codehaus snapshots. To configure Maven to use Nexus for both releases and plugins, you will have to configure Maven to reference the Nexus groups by adding the following mirror configuration to your Maven settings in ~/.m2/settings.xml.

<settings>
  <mirrors>
    <mirror>
      <!--This is used to direct the public snapshots repo in the 
          profile below over to a different nexus group -->
      <id>nexus-public-snapshots</id>
      <mirrorOf>public-snapshots</mirrorOf>
      <url>http://localhost:8081/nexus/content/groups/public-snapshots</url>
    </mirror>
    <mirror>
      <!--This sends everything else to /public -->
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://localhost:8081/nexus/content/groups/public</url>
    </mirror>
  </mirrors>
  <profiles>
    <profile>
      <id>development</id>
      <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>
    <profile>
      <!--this profile will allow snapshots to be searched when activated-->
      <id>public-snapshots</id>
      <repositories>
        <repository>
          <id>public-snapshots</id>
          <url>http://public-snapshots</url>
          <releases><enabled>false</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
     <pluginRepositories>
        <pluginRepository>
          <id>public-snapshots</id>
          <url>http://public-snapshots</url>
          <releases><enabled>false</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>development</activeProfile>
  </activeProfiles>
</settings>

$ mvn -Ppublic-snapshots clean install

16.4.3. Adding Custom Repositories for Missing Dependencies

If you've configured your Maven settings.xml to list Nexus as a mirror for all public repositories and all public-snapshot repository, you might encounter projects which are unable to retrieve artifacts from your local Nexus installation. This usually happens because you are trying to build a project which has defined a custom set of repositories and snapshotRepositories in a pom.xml. This is definitely going to happen if you are building open source projects or if you've added custom third-party Maven repositories to your configuration.

As an example, let's try to build Apache Shindig from source we've checked out of the Apache Incubator. What is Apache Shindig? It doesn't matter to this example; all we need is an example project we can easily checkout from source control and build. If you really want to know, Shindig is a project in the Apache Incubator that revolves around the OpenSocial API from Google. Shindig aims to provide a container that will allow people to execute OpenSocial gadgets. It provides us with an interesting example project, because it depends on some custom Maven repositories for components which have yet to be added to the Central Maven repository. Using Shindig we can show you what happens when Nexus doesn't have your artifacts and what steps you can take to add repositories to Nexus.

The following example assumes that you have Subversion installed and that you are running Subversion from the command-line. Let's checkout Apache Shindig from the Apache Incubator with Subversion and attempt to build it from source. To do this, execute the following commands:

$ svn co http://svn.apache.org/repos/asf/incubator/shindig/trunk shindig
... Subversion will checkout the trunk of Apache Shindig ...
$ cd shindig
$ mvn install
... Maven will build Shindig ...
Downloading: http://localhost:8081/nexus/content/groups/public/caja/caja/r2178/caja-r2178.jar
...
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failed to resolve artifact.

Missing:
----------
1) caja:caja:jar:r2178

  Try downloading the file manually from the project website.

...
----------
3 required artifacts are missing.

for artifact: 
  org.apache.shindig:shindig-gadgets:jar:1-SNAPSHOT

from the specified remote repositories:
  nexus (http://localhost:8081/nexus/content/groups/public)

The build fails because it is unable to download three artifacts. One of the artifacts Maven was trying to download has a group identifier of caja, and artifactId of caja, and a version of r2178. It is an artifact that is hosted on a custom repository http://google-caja.googlecode.com/svn/maven. Maven failed to download this artifact because your settings.xml was configured to direct all mirrors to the public and public-snapshots groups hosted on our Nexus installation. Even though the pom.xml for Apache Shindig defined a repository and pointed it at http://google-caja.googlecode.com/svn/maven, Nexus won't retrieve an artifact from a repository it doesn't know about and you've configured all requests for remote artifacts to pass through Nexus. In fact, there are two repositories that Nexus doesn't know about in this build: caja and oauth. Caja and OAuth are two libraries which are still in development. Both projects have been "released", and the versions that Shindig depends upon are certainly not SNAPSHOT releases, but these projects have not been published to the Central Maven Repository. We need to find a way to let Nexus know about these repositories before we can build this project.

There are two ways to fix this problem. First, you can change your settings.xml to override specific repository identifiers. Instead of listing the Nexus public group as a mirrorOf all repositories, you could change the mirrorOf element in your settings.xml to "central". If you did this, Maven would then attempt to download the dependencies directly from the oauth and caja repositories at the URLs listed in the previous screen listing. This would work because Maven is only going to consult Nexus for repositories which match the repositories specified in the mirrorOf element in settings.xml. If Maven sees the repositories identifier caja or oauth, and doesn't see a mirror configured in your settings.xml, it is going to attempt to connect to the repository directly.

The second, more interesting option is to add both of these repositories to Nexus and then add these repositories to the public group.

16.4.4. Adding a New Repository

To add the caja repository, log into Nexus as an Administrator, and click on the Repositories link in the left-hand navigation menu in the Configuration section. Clicking on this link should bring up a window that lists all of the repositories which Nexus knows about. You'll then want to create a new proxy repository. To do this, click on the Add link which is directly above the list of repositories. When you click the Add button, click the down arrow directly to the right of the word Add, this will show a drop-down which has the options: Hosted, Proxy, and Virtual. Since you are creating a proxy repository, click on Proxy. Once you do this, you will see a screen resembling Figure 16.9, “Adding a Nexus Repository”. Populate the required fields Repository ID and the Repository Name with "caja" and "Google Caja". Set the Repository Policy to "Release", and the Remote Storage Location to http://google-caja.googlecode.com/svn/maven.

Figure 16.9. Adding a Nexus Repository

Once you've filled out this screen, click on the Save button. Nexus will then be configured with the caja proxy repository. Do the same thing for the oauth repository. Create a repository with the Repository ID of oauth, with a Release policy, and the Remote Storage Location of http://oauth.googlecode.com/svn/code/maven.

16.4.5. Adding a Repository to a Group

Next you will need to add both of these new repositories to the public Nexus Group. To do this, click on the Groups link in the left-hand navigation menu in the Configuration section. When you see the Group management screen, click on the public group. Clicking on the public group should bring up a screen which resembles Figure 16.10, “Adding New Repositories to a Nexus Group”.

Figure 16.10. Adding New Repositories to a Nexus Group

To add the two new repositories to the public Nexus Group, find the repositories in the Available Repositories list on the right, click on the repository you want to add and drag it to the left to the Ordered Group Repositories list. Once the repository is in the Ordered Group Repositories list you can click and drag the repository within that list to alter the order in which a repository will be searched for a matching artifact. Once the Google Caja and Google OAuth project repositories are added to the public Nexus Group, you should be able to build Apache Shindig and watch Maven download the Caja and OAuth artifacts from the respective repositories.

In the last few sections, you encountered a situation where you needed to add two custom repositories to a build in order to download two libraries (Google Caja and Google OAuth) which are not available in the central Maven repository. If you were not using a repository manager, you would have added these repositories to the repository element of your project's POM, or you would have asked all of your developers to modify ~/.m2/settings.xml to reference two new repositories. Instead, you used the Nexus repository manager to add the two repositories to the public group. If all of the developers are configured to point to the public group in Nexus, you can freely swap in new repositories without asking your developers to change local configuration, and you've gained a certain amount of control over which repositories are made available to your development team.

16.5.1. Customizing Server Configuration

In a real installation of Nexus, you'll probably want to customize the administrative password to something other than "admin123", and you might want to override the default directories that Nexus uses to store repository data. To do this, log in as the administrative user and click on Server under Configuration in the left-hand navigation menu. The server configuration screen is shown in Figure 16.11, “Nexus Server Configuration (File, SMTP, and HTTP Config)” and Figure 16.12, “Nexus Server Configuration (Security, App Server, and HTTP Proxy Config)”.

Figure 16.11. Nexus Server Configuration (File, SMTP, and HTTP Config)

Figure 16.12. Nexus Server Configuration (Security, App Server, and HTTP Proxy Config)

This screen allows you to change:

16.5.2. Managing Repositories

To manage Nexus repositories, log in as the administrative user and click on Repositories in the Configuration menu in the left-hand navigation menu. Nexus provides for three different kinds of repositories: