Deploying Nuxeo IDE Customizations

In this article, I have a tip for deploying Nuxeo customizations developed  using the Nuxeo Eclipse IDE.

But first let me first mention a few things about how to go about customizing Nuxeo.

There are two main methods for customizing the Nuxeo web application:

• Nuxeo Studio
• Nuxeo Eclipse IDE plugin

Nuxeo Studio

Nuxeo Studio is a cloud-based configuration tool.  It's available by subscription, but it's not required to have in order to use Nuxeo.  Actually, without Studio you don't miss out on any of the cool end-user Nuxeo product features, but by using it, you can save yourself a tremendous amount of development and administration time, and you'll also know that your configurations made in Studio are guaranteed to be automatically upgradable to future product versions of Nuxeo.  

Nuxeo without Studio is much harder.  If you don't use Studio you'll need to hand-code and debug quite a few configuration files.  That can involve writing a lot of XML, XHTML and other code, easily hundreds of lines of code even for simple configurations.  And while manually creating those files isn't really that complex, writing those files can be tedious, and it's easy to introduce syntax errors while writing them that may end up later costing you many hours of time trying to track down and fix. 

You can do a lot with Studio, and if you're serious about Nuxeo, you really should use it.  We've found, for example, that most projects we work on start out by developing a custom content model and designing associated create, view and edit forms.  With Nuxeo Studio, an analyst could easily build and test the content model and all associated forms without needing assistance from a developer.  Studio also allows you to graphically design workflows, set up automation tasks, and a lot more.

Nuxeo IDE

For many installations, using Nuxeo Studio for configuring your application is sufficient, but if you need to do even more in-depth customizations than what Studio lets you do, you can use Nuxeo's Eclipse plugin.  Nuxeo has great on-line documentation showing you how to use it.  Unlike Studio, the Nuxeo IDE is a tool that targets Java developers.

Using the Nuxeo Eclipse IDE you can extend and override parts of the Nuxeo application.  From a Nuxeo perspective within Eclipse you can create a Nuxeo project and then add artifacts to it.  You can then deploy your project changes, launch Tomcat and run and debug the Nuxeo application, all within the Eclipse environment.

Deploying the Project Bundle

Now for the tip.  

It's easy to hot reload Nuxeo projects within Eclipse using the Nuxeo IDE plugin.  That feature really speeds up development.  But when deploying your IDE-developed customizations to a new Nuxeo instance, there's an additional deployment file that you need to have in your project.

Nuxeo has an option in the IDE to jar all the files of your project.  To deploy your changes, you just create the jar and then drop it into the nxserver/bundles directory of your new instance and restart.

The option to jar is available by first right-clicking on your project in the Eclipse Nuxeo perspective and then selecting Nuxeo and Export Jar.

That's easy enough.  But there's one more thing you need to do to prepare the jar file for deployment on another server, and if you don't do it, you're likely to run into problems.  This step isn't needed when you're developing and deploying from within Eclipse and is easy to overlook when reading Nuxeo's explanation for how to use the Nuxeo Eclipse IDE.

Every time Tomcat is restarted, the nuxeo.war directory under nxserver will get redeployed and expanded.  Because of that, any files you may have attempted to manually add to the nuxeo.war area after a deployment will be lost the next time the war is redeployed.  

A feature of the Nuxeo Eclipse IDE is that after the war is expanded, the project's web asset files from the src/main/resources/web directory of your project will be automatically copied into the war area, modifying the standard Nuxeo instance with your customizations.

But when deploying your project jar file to another Nuxeo instance, if you just copy over the jar to the new instance, the web asset files in your jar won't be visible to Tomcat.  Similar to what is done automatically for you with the Eclipse hot reload, the web asset files need to be placed within the expanded war.  This can be done using the deployment-fragment.xml file.  This file needs to be placed in your project at the top of the directory src/main/resources/OSGI-INF, for example:

Here's an example of what you can put in that file:

<?xml version="1.0"?>
<fragment version="1">
  
  <extension target="application#MODULE"> 
    <module> 
      <java>${bundle.fileName}</java> 
    </module> 
  </extension>  
  
  <require>all</require>
  <install>
    <delete path="${bundle.fileName}.tmp"/>
    <unzip from="${bundle.fileName}" to="${bundle.fileName}.tmp"/>
    <copy from="${bundle.fileName}.tmp/web/nuxeo.war" to="/"/>
    <append from="${bundle.fileName}.tmp/OSGI-INF/I18n/com.formtek.nuxeo.xrefs.messages.properties" to="nuxeo.war/WEB-INF/classes/messages_en_US.properties" addNewLine="true"/>
    <append from="${bundle.fileName}.tmp/OSGI-INF/I18n/com.formtek.nuxeo.xrefs.messages.properties" to="nuxeo.war/WEB-INF/classes/messages_en.properties" addNewLine="true"/>
    <delete path="${bundle.fileName}.tmp"/>
  </install>  
</fragment>

You can see that the install section of the code unjars your bundle and copies over all assets that are under the web directory of your project to the corresponding area of the expanded nuxeo.war.

That's it.  With the deployment-fragment.xml file in place, your bundle will be correctly deployed into the target Nuxeo instance when Tomcat starts up.

The content of the deployment-fragment.xml file looks something like an ant build file.  It describes tasks that are run when the bundle file is loaded.  Some of the things that you can script in this file include:

• unzip or unjar files 
• create folders 
• move files
• delete files and folders
• append files

[Note that there was a problem in the initial release of Nuxeo 6.0 for handling hot reloads.  Future releases are fixed.  For the 6.0 release, this JIRA explains a workaround.]