Skip to content
This repository has been archived by the owner on Nov 19, 2020. It is now read-only.

Latest commit

 

History

History
252 lines (202 loc) · 9.62 KB

chapter-sites.asciidoc

File metadata and controls

252 lines (202 loc) · 9.62 KB
Raw

Site Repositories

{inall}

Introduction

{pro} and {oss} include a repository provider for hosting static websites - the 'Site' format. Hosted repositories with this format can be used to hold a Maven-generated website. This chapter details the process of configuring a site repository and configuring a simple Maven project to publish a Maven-generated project site to the repository manager.

Creating a New Maven Project

In this chapter, you will be creating a simple Maven project with a simple website that will be published to a '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

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

Configuring Maven for Site Deployment

To deploy a site to a '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 the repository manager.

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 website:

Distribution Management for Site Deployment
<distributionManagement>
  <site>
    <id>nexus</id>
    <url>dav:http://localhost:8081/nexus/content/sites/site/</url>
  </site>
</distributionManagement>

The URL in the distribution management does not change with the project versions automatically, 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 a hardcoded specific URL for your project version.

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 to the Maven site plugin configuration.

Configuring Version 3.4 of the Maven Site Plugin with 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.6</version>
          </dependency>
        </dependencies>
    </plugin>
  </plugins>
</build>

Adding Credentials to Your Maven Settings

When the Maven Site plugin deploys a site to a repository, it needs to supply the appropriate deployment credentials. 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 Site Deployment
<settings>
  <servers>
    <server>
      <id>nexus</id>
      <username>deployment</username>
      <password>deployment123</password>
    </server>
  </servers>
</settings>
Note
 Configuring Deployment Credentials for 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 repository manager.

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

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 {oss} as well as {pro}.

Add the Site Deployment Role

In the Maven Settings shown in Configuring Deployment Credentials for Site Deployment, you configured your Maven instance to use the default deployment user and password. To successfully deploy a site to the repository manager, 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 main menu, and click on the 'Add' button in the 'Role Management' section. This will trigger the display of the 'Add Roles' 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 closes, 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 publish a site to a Site repository, run mvn site-deploy from the sample-site/ project created earlier in this chapter. The Maven Site plugin will deploy this site to the repository manager 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 Website