Documentation Nexus Repository Manager 3.0

Chapter 13. Raw Repositories, Maven Sites and More

Available in Nexus Repository OSS and Nexus Repository Pro

13.1. Introduction

Nexus Repository Manager Pro and Nexus Repository Manager OSS include support for hosting, proxying and grouping static websites - the raw format. Hosted repositories with this format can be used to store and provide a Maven-generated website. Proxy repositories can subsequently proxy them in other servers. The raw format can also be used for other resources than HTML files exposed by straight HTTP-like browsable directory structures.

This chapter details the process of configuring raw repositories, configuring a simple Maven project to publish a Maven-generated project site and other use cases for raw repositories.

13.2. Creating a Hosted Raw Repository

To create a raw repository for hosting a static website, you simply create a new repository using the raw (hosted) recipe as documented in Section 4.3, “Repository Management”.

For the Maven site example in Section 13.3, “Creating and Deploying a Maven Site”, set the Name to site and change the Deployment policy to Allow redeploy.

After creating the new raw repository, it appears in the list of repositories with the name site provided earlier. The URL in the list can be used for deployment and access usage.

13.3. Creating and Deploying a Maven Site

13.3.1. Creating a New Maven Project

In this section, you are be creating a minimal Maven project with a simple website that can be published to the hosted raw repository created in Section 13.2, “Creating a Hosted Raw Repository”.

The following steps can be used to create a new Maven project:

  • Run the command mvn archetype:generate in a command line interface
  • Confirm the first prompt using the default selection (number will vary)
  • Confirm the default selection for the archetype version
  • Set the groupId to org.sonatype.books.nexus
  • Set the artifactId to sample-site
  • Confirm the default version of 1.0-SNAPSHOT
  • Confirm the preset package of org.sonatype.books.nexus
  • Confirm the properties configuration

After running the archetype:generate command, you will have a new project in a sample-site directory.

13.3.2. Configuring Maven for Site Deployment

To deploy a site to a raw repository in the repository manager, you need to configure the project’s distributionManagement, add site deployment information, and then update your Maven settings to include the appropriate credentials.

Add the following section to sample-site/pom.xml before the dependencies element. This section tells Maven where to publish the Maven-generated project website:

Distribution Management for Site Deployment. 

<distributionManagement>
  <site>
    <id>nexus</id>
    <url>dav:http://localhost:8081/repository/site/</url>
  </site>
</distributionManagement>

The URL in the distribution management is not parameterized, which means that any redeployment overwrites old content and potentially leaves old stale files behind. To have a new deployment directory for each version, change the URL to a parameterized setup or change the whole URL between deployments.

If you combine this approach with a redirector or a static page that links to the different copies of your site, you can e.g., maintain separate sites hosting your javadoc and other documentation for different releases of your software.

The dav protocol used by for deployment to the repository manager requires that you add the implementing library as a dependency of the Maven site plugin in your Maven project:

Dependency for the Maven Site Plugin for DAV Support. 

<build>
  <plugins>
    <plugin>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.4</version>
      <dependencies>
        <dependency>
          <groupId>org.apache.maven.wagon</groupId>
          <artifactId>wagon-webdav-jackrabbit</artifactId>
          <version>2.8</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

13.3.3. Adding Credentials to Your Maven Settings

When the Maven site plugin deploys a site, it needs to supply the appropriate deployment credentials to the repository manager. To configure this, you need to add credentials to your Maven settings. Edit your ~/.m2/settings.xml file and add the following server configuration to the servers element.

Configuring Deployment Credentials for Site Deployment. 

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

[Note]

Configuring Deployment Credentials for Site Deployment uses the default admin username and password. For real world usage you would use the username and password of a user with the privilege to write to the target repository.

13.3.4. Publishing a Maven Site

To publish the site to the hosted raw repository in the repository manager, run mvn site-deploy from the sample-site directory. The Maven site plugin will deploy this site to the repository using the credentials stored in your Maven settings:

Sample Maven Log from Deploying a Site. 

$ mvn site-deploy
[INFO] Scanning for projects...
[INFO] --------------------------
[INFO] Building sample-site 1.0-SNAPSHOT
...
[INFO] --- maven-site-plugin:3.4:site (default-site) @ sample-site ---
...
[INFO] Generating "About" report.
...
[INFO] --- maven-site-plugin:3.4:deploy (default-deploy) @ sample-site ---
http://localhost:8081/repository/site/ - Session: Opened
[INFO] Pushing /Users/manfred/training/sample-site/target/site
[INFO]    >>> to http://localhost:8081/repository/site/./
...
 Transfer error: java.io.IOException: Unable to create collection: http://localhost:8081/repository/; status code = 400
Uploading: .//project-summary.html to http://localhost:8081/repository/site/

##http://localhost:8081/repository/site/./project-summary.html - Status code: 201

Transfer finished. 5078 bytes copied in 0.075 seconds
http://localhost:8081/repository/site/ - Session: Disconnecting
http://localhost:8081/repository/site/ - Session: Disconnected
...
[INFO] BUILD SUCCESS
...

Once the site has been published, you can load the site in a browser by going to http://localhost:8081/repository/site/index.html.

figs/web/sites-sample-site.png

Figure 13.1. Maven-Created Sample Site Hosted in a Raw Repository


[Tip]

A complete Maven project example can be found in the documentation book examples.

13.4. Proxying and Grouping Raw Repositories

Beside the common use case using hosted raw repositories for site deployments, the repository manager supports proxying as well as grouping of raw repositories.

The creation follows the same process as documented in Section 4.3, “Repository Management” using the raw (proxy) and the raw (group) recipes.

A raw proxy repository can be used to proxy any static website. This includes a Maven site hosted in a raw repository in another Nexus Repository Manager server or a plain static website hosted on another web server like Apache httpd. It can also be used to proxy directory structures exposed via a web server to distribute archives such as https://nodejs.org/dist/.

[Note]

No content is modified when proxied. This means that e.g., any absolute URL used with HTML document remain absolute and therefore bypass the proxying mechanism.

Grouping raw repositories is possible and can e.g., be used to aggregate multiple site repositories. However keep in mind that the raw format does not contain any logic to resolve conflicts between the different repositories in the group. Any request to the group causes the repository manager to check the member repositories in order and return the first matching content.

13.5. Uploading Files to Hosted Raw Repositories

Many other tools, besides using Maven, can be used to upload files to a hosted raw repository. A simple HTTP PUT can upload files. The following example uses the curl command and the default credentials of the admin user to upload a test.png file to a hosted raw repository with the name documentation.

An Example Upload Command Using curl

curl -v --user 'admin:admin123' --upload-file ./test.png http://localhost:8081/repository/documentation/test.png

After a completed upload the repository manager provides the file at the URL http://localhost:8081/repository/documentation/test.png. Using this approach in a script entire static websites or any other binary resources can be uploaded.