Skip to main content

Raw Repositories

Introduction

Nexus Repository includes 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 section 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.

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 Repository Management.

For the Maven site example in Creating and Deploying a Maven Site, set the Name to site and change the Deployment policy to Allow redeploy and a Content Dispositionof Inline.

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

Note

Disable the Strict Content Type Validation if you encounter problems related to the content MIME-type.

Creating and Deploying a Maven Site

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 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.

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.9.1</version>
      <dependencies>
        <dependency>
          <groupId>org.apache.maven.wagon</groupId>
          <artifactId>wagon-webdav-jackrabbit</artifactId>
          <version>2.8</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>

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>
    <!--your existing servers are here if any-->
    <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.

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] &gt;&gt;&gt; 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.

330733.png

Figure: Maven-Created Sample Site Hosted in a Raw Repository

Tip

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

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 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.

Content Disposition

The Content-Disposition response header indicates if the content in your raw repository should be displayed inline in the browser (i.e., as a web page) or as an attachment that a user downloads. By default, new raw repositories are assigned a Content-Disposition header of Attachment. However, if you would like to change this to Inline, you may do so by modifying the Content Disposition field in the configuration options for your raw repository.

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.

A complete static website consisting of numerous HTML, CSS, JS and image files or some other directory structure of multiple files and resources can be uploaded with a script that assembles and issues numerous HTTP PUT requests.

The raw folder of the nexus-book-examples repository contains the Groovy script rawPopulator.groovy as an example of such a script as well as a simplistic website of two HTML pages in the site directory. You can upload the directory to a raw repository with the name documentation to your repository manager at http://repo.example.com:8081 with:

Example invocation of the rawPopulator script

$ groovy rawPopulator.groovy -d site -r documentation -u admin -p admin123 -h http://repo.example.com:8081
Staging 2 files for publishing
pushing site/index.html
POST response status: HTTP/1.1 201 Created
pushing site/success.html
POST response status: HTTP/1.1 201 Created

After the upload, you can access the site at http://repo.example.com:8081/repository/documentation/ to load index.html and clicking on the link directs you to the success.html page.