Deploy your site on Nexus™ OpenSource

These days I have to provide a documentation site to one customer, so I started playing around with the maven site plugin and I created a really beautiful set of pages that will be able to teach all the details of my project to a chimp. Now, it’s time to make it available for that chimp: since my artifacts are delivered through Maven on a Nexus handled repository, I opted for the same Nexus instance to host my site. Let’s see what’s needed to achieve this result.

First of all, you have to download Nexus™. The OpenSource version is fine, so that you can start to play around before you eventually decide it’s time to go Pro. You can get Nexus from here. In the following I’ll assume you downloaded the quick start bundle, so that you’ll have a separated application server for Nexus shipped within the same zip file you downloaded. If you opted for the WAR download, you probably already know how to go

Configure & run Nexus

The default configuration provided with Nexus is probably fine for having just a quick try, but I suggest to configure one or two things, just to start feeling comfortable with the nice toy you’ve just downloaded. So, unzip the Nexus archive whereve you prefere, you will end up with a folder named like nexus-webapp-blabla. We will call it $NEXUS_HOME.

Open the file $NEXUS_HOME/conf/plexus.properties. Here I changed only two lines, namely the TCP port where the application will bind to and the storage area where all the artifacts (and sites!) will be stored. Here is my configuration file:

application-port=8082
application-host=0.0.0.0
runtime=${basedir}/runtime
apps=${runtime}/apps
nexus-work=/var/sonatype-work/nexus-opensource
webapp=${runtime}/apps/nexus/webapp
webapp-context-path=/nexus
security-xml-file=${nexus-work}/conf/security.xml
application-conf=${nexus-work}/conf
 
# If this file is present, it will be used to configure Jetty.
jetty.xml=${basedir}/conf/jetty.xml
 
# Uncomment this to use the debug js files
#index.template.file=templates/index-debug.vm

Since I changed the storage area, I had to create the folder configured in nexus-work:

~ skuro$ cd /var
var skuro$ sudo mkdir -p sonatype-work/nexus-opensource
var skuro$ sudo chgrp -R admin sonatype-nexus
var skuro$ sudo chmod -R g+rwx sonatype-nexus

NOTE: the permission you set on the created folders must match the user under which you’ll run Nexus.

Now it’s time to let it run. Nexus comes shipped with wrapper scripts that are able to launch the application on several different platforms. I’m running MacOSX on an Intel machine, but you’ll have to check inside the $NEXUS_HOME/bin/jsw folder to find the wrapper that best suits your system configuration.

~ skuro$ cd $NEXUS_HOME
nexus-webapp-1.3.4 skuro$ ./bin/jsw/macosx-universal-32/nexus start

Done. Now if you point your browser to http://localhost:8082/nexus you should see it’s dashboard:

The default admin username/password is admin/admin123, you can log in now and play around Nexus.

Configuring a repo for your sites

You don’t want to mess up artifacts and sites, it will be a lot neater if you have a separated repo for each kind of deliverable. When logged in as admin in Nexus, click the Repositories link on the left menu and then select Add->Hosted repository. A form will appear where you will have to enter the details of the repo you’re creating. Edit it to look like this:

Click on Save and the new repo will appear on the Repositories list, with the base URL you will have to use in your POM configuration. But let’s stick on Nexus configuration for now, we still have something to do here. Let’s create a Repository Target, which will be used to fine tune our configuration for our test project. Click on the Repository Targets in the Administration menu on the left and then Add. Another form will appear which you’ll fill like this:

OK, we’re almost there, we just have to set some authorization stuff and we’ll be done with Nexus. In Nexus, the security model is made of Privileges, which describe actions like “read” and “write”, Roles, that define a set of Privileges, and Users, to whom you can grant both Roles and Privileges. So, first of all click on the Permissions link from the left menu, and then Add->Repository Target Privilege. You’ll end up with something like this:

The Role and User creation is really straightforward, I’ll leave it to you to figure out how to create a Role that aggregates the Site repo privileges and a User that will be granted that role. In my test configuration, the User and the Role are both called site-dev.

Configuring the Maven site plugin

Now that we created a repo to host our sites, let’s try to deploy something in it! We have to do basically two things

• create a project, if we don’t have one already
• configure the repository where the site will be deployed in the distributionManagement section of the POM
• configure the user credential that will be used to upload the site

Developers are supposed to be lazy, otherwise automating things won’t be that effective. Knowing that, you can use this test-site-project to test your configuration. It is already a project with a parent POM and a module, just to prove that multi module projects are not an issue here

Before uploading the site, make sure that the site URL in the parent pom.xml matches your Nexus URL, and add a configuration in your $MAVEN_HOME/settings.xml to identify your user against Basic HTTP when deploying the site:

<server>
      <id>nexus-local-opensource</id>
      <username>site-dev</username>
      <password>password</password>
</server>

Remember that the site <id> must match the distributionManagement repository <id>.

Deploy it!

Ok, we got it, now we have a (hopefully) working configuration we can use to upload and make available your site through Nexus. To prove yourself that ir really works, just run this commands:

test-site skuro$ mvn site:site
test-site skuro$ mvn site:deploy

Done! Now, if you used the configuration I showed you, you should be able to access the site at the URL http://localhost:8082/nexus/content/repositories/site-repo/test-site/index.html

Conclusions

Using Nexus as a single provider for both your artifacts and the associated sites can be easier to maintain, and I hope this post will help you to start using this configuration. The next step will be the configuration for the maven release plugin, that can be easily achieved using maven CALM. But this is stuff for another post, so if you want to know more about it just search the Net [1] [2] or stay tuned!