Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 301 lines (246 sloc) 10.723 kb

Deploying Sites to Nexus

Introduction

Nexus provides a repository provider for hosting static websites - the "Site" format. Hosted repositories with this format can be used to hold a Maven-generated web site. This chapter details the process of configuring a site repository and configuring a simple Maven project to publish a Maven-generated project site to an instance of Nexus.

Creating a New Maven Project

In this chapter, you will be creating a simple Maven project with a simple web site that will be published to a Nexus Site repository. To create a new Maven project, use the archetype plugin’s archetype:generate goal on the command line, and supply the following identifiers:

  • groupId: org.sonatype.books.nexus

  • artifactId: sample-site

  • version: 1.0-SNAPSHOT

  • package: org.sonatype.books.nexus

~/examples$ mvn archetype:generate
[INFO] [archetype:generate {execution: default-cli}]
[INFO] Generating project in Interactive mode
Choose archetype:
1: internal -> appfuse-basic-jsf
...
13: internal -> maven-archetype-portlet (A simple portlet application)
14: internal -> maven-archetype-profiles ()
15: internal -> maven-archetype-quickstart ()
...
Choose a number:  (...14/15/16...) 15: : 15
Define value for groupId: : org.sonatype.books.nexus
Define value for artifactId: : sample-site
Define value for version:  1.0-SNAPSHOT: : 1.0-SNAPSHOT
Define value for package:  org.sonatype.books.nexus: : org.sonatype.books.nexus
Confirm properties configuration:
groupId: org.sonatype.books.nexus
artifactId: sample-site
version: 1.0-SNAPSHOT
package: org.sonatype.books.nexus
Y: :
[INFO] Parameter: groupId, Value: org.sonatype.books.nexus
[INFO] Parameter: packageName, Value: org.sonatype.books.nexus
[INFO] Parameter: package, Value: org.sonatype.books.nexus
[INFO] Parameter: artifactId, Value: sample-site
[INFO] Parameter: basedir, Value: /private/tmp
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
[INFO] OldArchetype created in dir: /private/tmp/sample-site
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 23 seconds
[INFO] Finished at: Sat Oct 03 07:09:49 CDT 2009
[INFO] Final Memory: 13M/80M
[INFO] ------------------------------------------------------------------------

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

Configuring Maven for Site Deployment

To deploy a site to a Nexus Site repository, you will need to configure the project’s distribution management settings, add site deployment information, and then update your Maven settings to include the appropriate credentials for Nexus.

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

Distribution Management for Site Deployment to Nexus
<distributionManagement>
  <site>
    <id>nexus-site</id>
    <url>dav:http://localhost:8081/nexus/content/sites/site/</url>
  </site>
</distributionManagement>
Note
In Distribution Management for Site Deployment to Nexus, there is a Nexus installation running on localhost port 8081. In your environment you will need to customize this URL to point to your own Nexus instance.

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 you can change the url to a parameterized setup.

Parameterized Distribution Management for Site Deployment
<url>
dav:http://localhost:8081/nexus/content/sites/site/${project.groupId}/${project.artifactId}/${project.version}
</url>

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 release of your software.

The dav protocol used by for deployment to Nexus requires that you add the implementing library as a build extension to your Maven project:

Build Extension for DAV Support
 <build>
   <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-webdav-jackrabbit</artifactId>
        <version>2.6</version>
      </extension>
    </extensions>

In addition to the distributionManagement element and the build extension, you will want to add the following build element that will configure Maven to use version 3.2 of the Maven Site plugin.

Configuring Version 3.2 of the Maven Site Plugin
<build>
  <plugins>
    <plugin>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.3</version>
    </plugin>
  </plugins>
</build>

Adding Credentials to Your Maven Settings

When the Maven Site plugin deploys a site to Nexus, it needs to supply the appropriate deployment credentials to Nexus. To configure this, you need to add credentials to your Maven Settings. Open up your ~/.m2/settings.xml and add the following server configuration to the servers element.

Configuring Deployment Credentials for Nexus Site Deployment
<settings>
  <servers>
    <server>
      <id>nexus-site</id>
      <username>deployment</username>
      <password>deployment123</password>
    </server>
  </servers>
</settings>
Note
Configuring Deployment Credentials for Nexus Site Deployment, uses the default deployment user and the default deployment user password. You will need to configure the username and password to match the values expected by your Nexus installation.

Creating a Site Repository

To create a site repository, log in as a user with Administrative privileges, and click on "Repositories" under Views/Repositories in the Nexus menu. Under the Repositories tab, click on the Add… drop-down and choose "Hosted Repository" as shown in Adding a Hosted Repository.

sites add hosted
Figure 1. Adding a Hosted Repository

In the New Hosted Repository form, click on the Provider drop-down and chose the Site provider as shown in Creating a New Maven Site Repository. Although you can use any arbitrary name and identifier for your own Nexus repository, for the chapter’s example, use a Repository ID of "site" and a Repository Name of "Maven Site".

sites new repo
Figure 2. Creating a New Maven Site Repository

After creating a new Site repository, it should appear in the list of Nexus repositories as shown in Newly Created Site Repository. Note that the Repository Path shown in Newly Created Site Repository, is the same as the repository path referenced in Distribution Management for Site Deployment to Nexus.

sites new repo listed
Figure 3. Newly Created Site Repository
Tip
The Site provider support is implemented in the Nexus Site Repository Plugin and is installed by default in Nexus Open Source as well as Nexus Professional.

Add the Site Deployment Role

In the Maven Settings shown in Configuring Deployment Credentials for Nexus Site Deployment, you configured your Maven instance to use the default deployment user and password. To successfully deploy a site to Nexus, you will need to make sure that the deployment user has the appropriate role and permissions. To add the site deployment role to the deployment user, click on Users under the Security section of the Nexus menu, and click on the Add button the Role Management section. This will trigger the display of the Add Role dialog that will allow you to apply a filter value of Site to locate the applicable roles as shown in Adding the Site Deployment Role to the Deployment User.

sites deploy role
Figure 4. Adding the Site Deployment Role to the Deployment User

Check the box beside the "Repo: All Site Repositories (Full Control)" role in the list and press OK in the dialog. After the dialog closed, you should see the new role in the Role Management section. Click on the Save button to update the roles for the deployment user. The deployment user now has the ability to publish sites to a Maven Site repository.

Publishing a Maven Site to Nexus

To publish a site to a Maven Site repository in Nexus, run mvn site-deploy from the sample-site/ project created earlier in this chapter. The Maven Site plugin will deploy this site to Nexus using the credentials stored in your Maven Settings.

~/examples/sample-site$ mvn site-deploy
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building sample-site
...
[INFO] Generating "About" report.
[INFO] Generating "Issue Tracking" report.
[INFO] Generating "Project Team" report.
[INFO] Generating "Dependencies" report.
[INFO] Generating "Project Plugins" report.
[INFO] Generating "Continuous Integration" report.
[INFO] Generating "Source Repository" report.
[INFO] Generating "Project License" report.
[INFO] Generating "Mailing Lists" report.
[INFO] Generating "Plugin Management" report.
[INFO] Generating "Project Summary" report.
[INFO] [site:deploy {execution: default-cli}]
http://localhost:8081/nexus/content/sites/site/ - Session: Opened
Uploading: ./css/maven-base.css to http://localhost:8081/nexus/content/sites/site/

#http://localhost:8081/nexus/content/sites/site//./css/maven-base.css \
- Status code: 201

Transfer finished. 2297 bytes copied in 0.052 seconds
Uploading: ./css/maven-theme.css to http://localhost:8081/nexus/content/sites/site/

#http://localhost:8081/nexus/content/sites/site//./css/maven-theme.css \
- Status code: 201

Transfer finished. 2801 bytes copied in 0.017 seconds

Transfer finished. 5235 bytes copied in 0.012 seconds
http://localhost:8081/nexus/content/sites/site/ - Session: Disconnecting
http://localhost:8081/nexus/content/sites/site/ - Session: Disconnected
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 45 seconds
[INFO] Finished at: Sat Oct 03 07:52:35 CDT 2009
[INFO] Final Memory: 35M/80M
[INFO] ------------------------

Once the site has been published, you can load the site in a browser by going to http://localhost:8081/nexus/content/sites/site/

sites sample site
Figure 5. Sample Site Maven Project Web Site
Something went wrong with that request. Please try again.