Skip to main content

Quick Start Guide - Proxying Maven and NPM

If you're new to Nexus Repository 3, use this guide to get familiar with configuring the application as a dedicated proxy server for Maven and npm builds.

To reach that goal, follow each section to:

  • Install Nexus Repository 3

  • Run the server locally for testing

  • Proxy a basic Maven and npm build

When you complete the steps, the components will be cached locally to your server. After meeting the requirements, it will take approximately 15 minutes to proxy Maven and npm with the code snippets below.

Requirements

Before you can set up the proxy server for Maven and npm, you'll need to install and configure the following external tools for the repository manager:

Supported Java Version

Sonatype Versions Supporting This Java Version

Java 8

  • Supported for all currently released versions

  • Required for versions up to and including 3.66.0

Java 11

  • 3.67.0 and above

Java 17

  • 3.69.0 and above

  • Not supported in OrientDB environments

  • A Java Development Kit (JDK) in a supported version as detailed in the table below - Nexus Repository 3 is a Java server application

  • Apache Maven - Nexus Repository 3 includes a proxy configured to Central Repository when you first start up.

    • For the maven client to use Nexus Repository to request dependencies, you will want to define this proxy repository in both your settings.xml file and the Project Object Model file (POM).

  • npm - A popular repository for javascript components.

    • Nexus Repository 3 doesn’t ship configured wiith a proxy to the npm repository.

      • You will first need to add this proxy repository to Nexus Repository.

      • Then configure your npm client to access the newly created proxy by updating the .npmrc configuration file as shown below.

Part 1 - Installing and Starting Nexus Repository Manager 3

  1. Create an installation directory in your desired location.

  2. Download the most recent repository manager for your operating system.

  3. If the file is downloaded to a location outside the installation directory, move it there.

  4. Unpack the .tar.gz or .zip file in its new location. Both an application (i.e. nexus-<version>) and data directory (i.e. ../sonatype-work/nexus3) are created after extraction.

  5. Go to the application directory which contains the repository manager file you need to start up.

  6. In the application directory, run the startup script launching the repository manager:

    • Linux or Mac: ./bin/nexus run

    • Windows: bin/nexus.exe /run

  7. Wait until the log shows the message “Started Sonatype Nexus.”

  8. Open your browser and type "http://localhost:8081/" in your URL field.

  9. From the user interface click Sign In, which generates a modal to enter your credentials.

  10. Navigate to ../sonatype-work/nexus3/ in your terminal.

  11. Locate the admin.password file.

  12. Copy the string from the file to the password field, and sign in.

  13. Complete the step-by-step setup modal to update your password and set Anonymous Access defaults upon logging in.

Part 2 - Proxying Maven and npm Components

When you proxy components the repository manager acts as a local intermediary server for any download requests going to remote repositories / registries. After logging in, these next steps will show you how to configure then test your configuration with local builds for a Maven and npm project.

Maven

NOTE: If you have an existing Maven configuration file (settings.xml) that you want to retain, back it up before doing any modifications.

  1. In your Maven file directory, open your settings.xml and change the contents of the snippet below. You can find this file in .m2, e.g ~/.m2/settings.xml.

    <settings>
    <mirrors>
      <mirror>
      <!--This sends everything else to /public -->
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>http://localhost:8081/repository/maven-public/</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>
  2. Go to the repository manager user interface.

  3. Click Administration in the left navigational menu, then click Repositories.

  4. Click Create repository and choose the maven2 (proxy) recipe from the list.

  5. Add the following text in the required fields:

  6. Click Create repository to complete the form.

  7. From the command-line interface, create the POM file (pom.xml) 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>
  8. Run the Maven build with the command mvn package.

NOTE: If you to want to view the details of your Maven test build, skip to Part 3. However, if you want to test an npm build, continue to the next section in this part.

npm

NOTE: If you have an existing npm configuration file (.npmrc) that you want to retain, back it up before doing any modifications.

Note

Once you create an npm proxy repository, do not change the remote server URL. Doing so may result in 404s as Nexus Repository attempts to retrieve cached data. Instead, create a new proxy repository.

  1. Click Administration in the left navigational menu, then click Repositories.

  2. Click Create repository and choose npm (proxy) from the list.

  3. Add the following text in the required fields:

  4. From the command-line interface run npm config set registry http://localhost:8081/repository/npm-proxy.

  5. From the command-line interface, create a package.json with the values below:

    {
    "name": "sample_project1",
    "version": "0.0.1",
    "description": "Test Project 1",
    "dependencies" : {
      "commonjs" : "0.0.1"
    }
    }
  6. Run the npm build with the command npm install.

Part 3 - Viewing Proxied Components

After your Maven and npm projects are successfully built, follow these steps to view the cached components:

  1. Click Browse from the main toolbar.

  2. Click Components.

  3. Of your components, choose maven-proxy or npm-proxy. You’ll see the test component you proxied for the respective format during the previous build steps.

  4. Click on a component name to review its details.

  5. The Components screen is a sub-section to the Browse interface. In order to view other components, click Components directly from the current screen and select another repository name from step 3 in this part.