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 Disposition of 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.
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:generatein 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
- Set the
- Confirm the default version of
- 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
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.
<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.
<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:
<settings> <servers> <!--your existing servers are here if any--> <server> <id>nexus</id> <username>admin</username> <password>admin123</password> </server> </servers> </settings>
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:
$ 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
Figure: Maven-Created Sample Site Hosted in a Raw Repository
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
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.
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
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
$ 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