Repository Management with Nexus

22.3. The Basics: Proxying and Publishing

 

After a few weeks the importance of having a repository manager is so obvious no one on my team can believe we used to develop software without one.

 
  -- Build Engineer Financial Industry

If you are new to repository management, the first step is to evaluate the two basic benefits of running a repository manager: proxying and publishing.

You can reap these benefits with any build Java/JVM build system that includes declarative dependency management and understands the Maven repository format. In the following we are going to cover the details for Apache Maven, Gradle and Apache Ant/Apache Ivy based builds. Build tools like SBT, Leiningen, Gant/Grails and others can be configured to do the same and get access to the same benefits.

22.3.1. Proxying Components

If you use a dependency in your software, your build downloads components from a remote repository, such as the Central Repository and others. Your systems depend on these components. If one of these critical remote repositories becomes unavailable, your productivity can grind to a halt.

This is where Nexus can help. Nexus is pre-configured to proxy the Central Repository and other remote repositories can be easily added. Once set up, Nexus maintains a local cache of the needed components from the remote repositories for you. Your build is more reliable when all the components you require are cached by Nexus. It is providing you with dramatic efficiency and speed improvements across your entire development effort.

In this example, you will…

  • Configure your build to download components from Nexus
  • Pre-cache dependencies and build components with an initial build
  • Note organization-wide improvements in build reliability

Let’s get started using the provided scripts:

The eval bundle includes an installation of Apache Maven as well scripts that isolate your evaluation from the rest of your system and make it extremely easy for you to follow. The Gradle examples use a wrapper script to allow you to simply follow the example. To follow the Ant/Ivy examples you will have to install Apache Ant as explained in Section 22.1.5, “Apache Ant and Apache Ivy”.

  1. Go to the Nexus evaluation guide directory you configured during the Nexus Professional install, which is named evalguide by default and can be found in your users home directory, and run the command

    $ cd maven
    $ ./build -f simple-project/pom.xml clean install

    to use Apache Maven or if you want to try Gradle use

    $ cd gradle/simple-project
    $ ./gradlew build

    With Apache Ant and Ivy you can run

    $ cd ant-ivy/simple-project
    $ ant jar
  2. As the project builds, you will notice that all components are downloaded from your local Nexus instance installed with requests from Apache Maven like

    Downloading: http://localhost:8081/nexus/content/groups/public/org
      /apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom
    Downloaded: http://localhost:8081/nexus/content/groups/public/org
      /apache/maven/plugins/maven-clean-plugin/2.5/maven-clean-plugin-2.5.pom
      (4 KB at 1.3 KB/sec)
    ...

    or from Gradle

    Download http://localhost:8081/nexus/content/groups/public/org/
      codehaus/jackson/jackson-core-asl/1.8.0/jackson-core-asl-1.8.0.jar
    Download http://localhost:8081/nexus/content/groups/public/org/
      codehaus/jackson/jackson-mapper-asl/1.8.0/jackson-mapper-asl-1.8.0.jar
    Download http://localhost:8081/nexus/content/groups/public/com/
      google/sitebricks/sitebricks-converter/0.8.5/sitebricks-converter-0.8.5.jar
    ...

    or from Apache Ivy

    [ivy:retrieve] downloading http://localhost:8081/nexus/content/
      groups/public/asm/asm-commons/3.2/asm-commons-3.2.jar ...
    [ivy:retrieve] .. (32kB)
    [ivy:retrieve] .. (0kB)
    [ivy:retrieve]  [SUCCESSFUL ] asm#asm-commons;3.2!asm-commons.jar (313ms)
    ...
  3. After the build has successfully completed, delete the local Maven repository cache in the eval guide directory and re-run the build as before

    $ cd maven
    $ rm -rf repository

    Delete the Gradle cache with

    $ rm -rf ~/.gradle

    or the Ivy cache with

    $ ant clean-cache clean
  4. Notice how the downloads are occurring much faster. The components are no longer retrieved from the remote repositories before being served by Nexus, but rather are supplied straight from the proxy repository cache in Nexus.
  5. To verify that components are being cached in Nexus, open the Repositories panel by clicking on Repositories in the left-hand Nexus menu. Once the list of repositories is displayed, select Central. Click on the Browse Storage tab and observe the tree of components downloaded and successfully cached in Nexus.

Alternatively using your own Apache Maven setup:

  1. Ensure that Apache Maven is installed as a prerequisite as documented in Section 22.1.3, “Apache Maven”.
  2. Go to the Nexus evaluation guide directory you configured during the Nexus Professional install and configure Maven to access Nexus with the provided settings.xml. Ensure to back up any existing settings file and adapt the port in the mirror url, if you have chosen to use a different port than 8081 in the Nexus trial installer.

    $ cp maven/settings/setttings.xml ~/.m2/
  3. Optionally, if you do not want to use the default local repository location of Maven in ~/.m2/repository, change the localRepository settings in the settings.xml file to an absolute path.
  4. Build the simple-project

    $ cd maven/simple-project/
    $ mvn clean install
  5. And observe the downloads from the Nexus repository as described above
  6. After the build has successfully completed, delete the local Maven repository cache and re-run the build.

    $ rm -rf ~/.m2/repository
  7. And notice the improved build performance and the cached components in Nexus as described earlier.

22.3.2. Publishing Components

Nexus makes it easier to share components internally. How do you distribute and deploy your own applications? Without Nexus, internal code is often distributed and deployed using an SCM, a shared file system, or some other inefficient method for sharing binary components.

With Nexus you create hosted repositories, giving you a place to upload your own components to Nexus. You can then feed your components back into the same repositories referenced by all developers in your organization.

In this example, you will…

  • Publish a component to Nexus
  • Watch another project download this component as a dependency from Nexus

Let’s get started using the provided scripts:

  1. Follow the proxying evaluation example from Section 22.3.1, “Proxying Components”
  2. Go to the Nexus evaluation guide directory and publish the simple-project to Nexus with the Maven wrapper script.

    $ cd maven
    $ ./build -f simple-project/pom.xml clean deploy

    With your own Maven installation you can use

    $ cd maven/simple-project/
    $ mvn clean deploy

    To deploy the project with Gradle you can run the commands

    $ cd gradle/simple-project
    $ ./gradlew upload

    The equivalent Ant invocation is

    $ cd ant-ivy/simple-project
    $ ant deploy
  3. The simple-project has been preconfigured to publish its build output in the form of a jar component to your local instance of Nexus Professional.
  4. Observe how the build tools log the deployment to Nexus e.g., Maven

    Uploading: http://localhost:8081/nexus/content/repositories/snapshots/
      org/sonatype/nexus/examples/simple-project/1.0.0-SNAPSHOT/
      simple-project-1.0.0-20130311.231302-1.jar
    Uploaded: http://localhost:8081/nexus/content/repositories/snapshots/
      org/sonatype/nexus/examples/simple-project/1.0.0-SNAPSHOT/
      simple-project-1.0.0-20130311.231302-1.jar (3 KB at 38.2 KB/sec)

    Gradle

    Uploading:
    org/sonatype/nexus/examples/simple-project/1.0-SNAPSHOT/
      simple-project-1.0-20130306.173412-1.jar
    to repository remote at
    http://localhost:8081/nexus/content/repositories/snapshots

    or Ivy

    [ivy:publish] :: publishing :: org.sonatype.nexus.examples#simple-project
    [ivy:publish]   published simple-project to http://localhost:8081
      /nexus/content/repositories/snapshots/org/sonatype/nexus/examples/
      simple-project/1.0-SNAPSHOT/simple-project-1.0-SNAPSHOT.jar
  5. To verify that the simple-project component was deployed to Nexus, click on Repositories and then select the Snapshots repository. Select the Browse Storage tab as shown in this illustration.

    figs/web/eval-publish.png

    Figure 22.2. Successfully Deployed Components in the Snapshots Repository


  6. Once this component has been published, return to the evaluation sample projects directory and run a build of another-project:

    $ cd maven
    $ build -f another-project/pom.xml clean install

    With your own Maven installation you can use

    $ cd maven/another-project
    $ mvn clean install

    To build the second project with Gradle, simply use

    $ cd gradle/another-project
    $ ./gradlew build

    Perform the same action with Ant using

    $ cd ant-ivy/another-project
    $ ant jar
  7. This second project has a dependency on the first project declared in the Maven pom.xml with

    <dependency>
      <groupId>org.sonatype.nexus.examples</groupId>
      <artifactId>simple-project</artifactId>
      <version>1.0.0-SNAPSHOT</version>
    </dependency>

    and in the Gradle build.gradle file as

    dependencies {
        compile "org.sonatype.nexus.examples:simple-project:1.0.0-SNAPSHOT"
    }

    Ivy declares the dependency in ivy.xml and it looks like this

    <dependencies>
      <dependency org="org.sonatype.nexus.examples" name="simple-project"
          rev="1.0.0-SNAPSHOT"/>
    </dependencies>

    During the build, it is relying on Nexus when it attempts to retrieve the component from simple-project.

Now that you are sharing components of your projects internally, you do not need to build each others software projects anymore. You can focus on writing the code for your own components and the integration of all components to create a larger software component. In fact it does not even matter, which build tool created the component, since the Maven repository format is understood by all of them.f