Nuxeo Add-Ons

Creating Nuxeo Packages

Updated: September 22, 2017 Page Information Edit on GitHub

This section gives instructions on how to wrap a plugin and its required dependencies into a Nuxeo Package.

A Nuxeo Package usually contains new features or patches along with installation instructions and optional constraints towards other packages (dependency, conflict). It is the easiest way to distribute a plugin, as it contains in one single ZIP file all the bundles, libraries, configuration properties and templates that are required to make the plugin work. Moreover, it is the most reliable and sustainable way to install a plugin, as it provides install history, rollback capabilities, dependencies and conflicts resolution and much more. Nuxeo uses the Nuxeo Package format for distributing all its plugins on the Nuxeo Marketplace. Nuxeo Packages are also recommended for delivering your customization.

The Nuxeo Packages can be managed either in the Admin page on the Nuxeo server, or using the nuxeoctl program.

Each package contains a description of the modifications that should be done on the server in order to install a plugin. We call "command" each atomic instruction of an install or uninstall process. The commands are revertible: for any command execution there is an inverse command that can be executed to rollback the modifications. While installing a package, Nuxeo generates the uninstall instructions (rollback commands) which will be executed either when the installation fails (in the middle of the install process), or when the package is uninstalled.

In this chapter we will discuss about the package format, package execution and rollback.

Package Format

A package is assembled as a ZIP file that contains the bundles, configuration files or libraries you want to install, along with some special files that describe the install process.

Here is a list of the special files (you should avoid to use these file names for installable resources)

  • package.xml - The package descriptor describing package metadata, dependencies and custom handlers to be used when installing. See Package Manifest for more details on the file format.
  • install.xml - A file containing the install instructions. There are two possible formats for this file: either an XML package command file, or an ant script to be used to install the package. Using ant is discouraged, you should envisage to use the package command to describe an installation rather than ant since rollback is ensured to be safe. See Scripting Commands for more details on the commands file format.
  • uninstall.xml - A file containing the uninstall instructions. When using commands to describe the install process this file will be automatically generated (so you don't need to write it). When using Ant for the install you must write the uninstall Ant file too.
  • install.properties - A Java property file containing user preferences (if any was specified during the install wizard). This file is automatically generated by the installer.
  • backup - A directory created by the install process (when using commands to describe the install) to backup the existing files that were modified. The content of this directory will be used by the rollback process to revert changes. See Scripting Commands for more details on rollback.
  • license.txt - A text file containing the license of the software you want to install. This file is optional.
  • content.html - A file containing an HTML description of your package. This file can use references to resources (such as images) located in the package zip - for example you may want to display a set of screenshots for the new feature installed by the package. This file is optional.
  • forms - A directory containing custom wizard form definitions. This directory and all the files inside are optional.

    Forms, which are base on the ParametrizedCopy command, are more or less deprecated since they currently work only under the following conditions (NXP-14777):

    • not under Windows,
    • MP is hotreloadable (NXP-8241),
    • DEV mode is activated.

    Instead, you should use a custom configuration template deployed and activated by the MP, then configured by the server administrator from nuxeo.conf.

    There are three type of wizard forms you can contribute:

    • install.xml - Describe install forms (i.e. forms added to the install wizard for packages that needs user parameterization)
    • uninstall.xml - Uninstall forms (i.e. forms added to the uninstall wizard for packages that needs user parameterization)
    • validation.xml - Validation forms (i.e. forms used by the install validator if any is needed)

Apart these special files you can put anything inside a package (web resources, jars, Java or Groovy classes etc.). It is recommended to group your additional resources in sub directories to keep a clean structure for your package.

You can see that most of the files listed above are optional or generated. So for a minimal package you will only need 2 files: the package.xml and the install.xml file.

Create an Empty Nuxeo Package

From a Maven Multi-Module Project

We assume that you already bootstrapped your project with Nuxeo CLI, or your project is following the mechanism describes by Maven as a multi-module project.

$ cd my-project
$ nuxeo bootstrap package

If you previously generated the project using Nuxeo CLI, then you will be prompted only for the package name. Otherwise, you will also be prompted for:

  • Parent Group ID - root POM groupId value.
  • Parent Artifact ID - root POM artifactId value.
  • Parent Version - root POM version value.
     info You'll be prompted for generation of:
     info   my-project-package: package

   create Generate Module: my-project-package

   create Generating Package
     info   Parameters: Parent group, Parent artifact, Parent version, Package artifact, Package version, Package name, Company name
? Parent Group id: org.nuxeo.sample.project
? Parent Artifact id: my-project-parent
? Parent version: 1.0-SNAPSHOT
? Package Artifact id: my-project-package
? Package name: My Project
? Company name: Nuxeo
   create my-project-package/pom.xml
   create my-project-package/src/main/assemble/assembly.xml
   create my-project-package/src/main/resources/install/templates/my-project/nuxeo.defaults
   create my-project-package/src/main/resources/install.xml
   create my-project-package/src/main/resources/package.xml
     info You can start editing code or you can continue with calling another generator (nuxeo bootstrap [<generator>..])

Run mvn package to generate your Nuxeo Package and read installing a Nuxeo Package to deploy it.

From a Maven Single Module Project

In order to create a dedicated package for a Maven single module project, you have to create a separate project that will contain a dependency to your project.

The following example assumes that your project's GAV is com.bigcorp.sample:my-big-project:1.0-SNAPSHOT.

$ cd my-project && cd .. # Move to the parent folder of your project root
$ mkdir my-project-package && cd $_ # Create a dedicated folder
$ nuxeo bootstrap package # Bootstrap package

You will be prompted for parent artifact informations; if your company is having a BOM you should know what to fill. Otherwise you can follow this example using nuxeo-distribution, it will brings all Nuxeo dependencies at once:

     info You'll be prompted for generation of:
     info   my-project-package: package

   create Generate Module: my-project-package

   create Generating Package
     info   Parameters: Parent group, Parent artifact, Parent version, Package artifact, Package version, Package name, Company name
? Parent Group id: org.nuxeo.ecm.distribution
? Parent Artifact id: nuxeo-distribution
? Parent version: 8.10
? Package Artifact id: my-project-package
? Package Version: 1.0-SNAPSHOT
? Package name: My Project
? Company name:
   create pom.xml
   create src/main/assemble/assembly.xml
   create src/main/resources/install/templates/my-project/nuxeo.defaults
   create src/main/resources/install.xml
   create src/main/resources/package.xml
     info You can start editing code or you can continue with calling another generator (nuxeo bootstrap [<generator>..])

You just created an empty package; without any additional dependency for now. Edit the newly created pom.xml file to add your projects:

  <dependencies>
    ...
    <!-- Additional bundles to be deployed by the MP -->
    <dependency>
      <groupId>org.bigcorp.project</groupId>
      <artifactId>my-project-core</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>

Run mvn package to generate your Nuxeo Package and read installing a Nuxeo Package to deploy it.

The Package Manifest

The package metadata is stored in package.xml file.

Here is the list of mandatory and highly recommended properties defining a package:

  • name: The package name.
  • version: The package version.
  • title: The package title to be displayed to the user.
  • type: The package type. One of: studio, hotfix, or addon.
  • platforms: A list of supported platform versions.
  • vendor: The identifier of the package vendor.
  • home-page: An URL to the home page of the package (or documentation) if any.
  • visibility: The visibility determines the channel where the package will be distributed on (for public, private or registered users).

For more information on the package properties and the XML format see the Package Manifest.

Scripting Commands

XML Commands are the default way to describe the installation instructions. The advantage of using commands is that the rollback and uninstall scripts will be automatically generated.

See Scripting Commands for more details on using commands.

Below is the list of available properties you can use in command files to parameterize your commands.

Context Properties Available in Scripting Commands

Here is the list of properties available to install scripts:

  • all the system properties in the running JVM.
  • package.id: The Package identifier.
  • package.name: The Package name.
  • package.version: The Package version.
  • package.root: The root folder of the package (the folder containing the exploded zip).
  • env.server.home: Since 5.5. The Nuxeo server home ($NUXEO_HOME).
  • env.home: The Nuxeo Runtime Environment home ($NUXEO_HOME/server/default/data/NXRuntime on JBoss, $NUXEO_HOME/nxserver on Tomcat).
  • env.ear: JBoss only. The nuxeo.ear directory ($NUXEO_HOME/server/default/deploy/nuxeo.ear).
  • env.lib: The Nuxeo lib directory (nuxeo.ear/lib on JBoss, $NUXEO_HOME/nxserver/lib on Tomcat).
  • env.syslib: The host application lib directory ($NUXEO_HOME/lib).
  • env.bundles: The Nuxeo bundles directory (nuxeo.ear/bundles on JBoss, $NUXEO_HOME/nxserver/bundles on Tomcat).
  • env.config: The Nuxeo config directory (nuxeo.ear/config on JBoss, $NUXEO_HOME/nxserver/config on Tomcat).
  • env.templates: The configuration templates directory ($NUXEO_HOME/templates).
  • env.hostapp.name: The host application name (Tomcat or JBoss)
  • env.hostapp.version: The host application version (e.g. Tomcat or JBoss version)
  • sys.timestamp: The timestamp when the install task was created - a string in the format yyMMddHHmmss.
3 days ago manonlumeau NXDOC-1323: Update BDE doc
a year ago Arnaud Kervern 54
a year ago Manon Lumeau 53
2 years ago Alain Escaffre 52
2 years ago Julien Carsique 51
2 years ago Ronan Daniellou 50 | Typo 'you package' -> your
2 years ago Solen Guitter 49
2 years ago Manon Lumeau 48
2 years ago Julien Carsique 47
2 years ago Julien Carsique 46
2 years ago Julien Carsique 45
2 years ago Julien Carsique 44
2 years ago Julien Carsique 43
3 years ago Solen Guitter 42
3 years ago Bertrand Chauvin 40
3 years ago Bertrand Chauvin 41
3 years ago Bertrand Chauvin 39
3 years ago Bertrand Chauvin 38
3 years ago Bertrand Chauvin 37 | Added link to NX IDE wizard page
3 years ago Solen Guitter 36
3 years ago Manon Lumeau 35
3 years ago Julien Carsique 34 | NXDOC-122: use configuration template instead of form
3 years ago Julien Carsique 33 | NXDOC-380: JIRA macro is broken
3 years ago Julien Carsique 32
3 years ago Julien Carsique 31 | NXDOC-122: ParametrizedCopy
4 years ago Solen Guitter 30 | Added TOC
4 years ago Alain Escaffre 28
4 years ago Alain Escaffre 29
6 years ago Solen Guitter 26 | replaced 5.4.3 with 5.5
6 years ago Solen Guitter 27 | Migrated to Confluence 4.0
6 years ago Julien Carsique 25 | NXP-6139 - add the templates folder as an env variable to the Update Center installer framework
7 years ago whajeri 24
7 years ago whajeri 23
7 years ago Stéfane Fermigier 22
7 years ago Stéfane Fermigier 21
7 years ago Eric Barroca 20
7 years ago Jane Zupan 19
7 years ago Alain Escaffre 18
7 years ago Bogdan Stefanescu 17
7 years ago Bogdan Stefanescu 16
7 years ago Bogdan Stefanescu 15
7 years ago Bogdan Stefanescu 14
7 years ago Bogdan Stefanescu 13
7 years ago Bogdan Stefanescu 12
7 years ago Bogdan Stefanescu 11
7 years ago Bogdan Stefanescu 10
7 years ago Bogdan Stefanescu 9
7 years ago Bogdan Stefanescu 8
7 years ago Bogdan Stefanescu 7
7 years ago Bogdan Stefanescu 6
7 years ago Bogdan Stefanescu 5
7 years ago Bogdan Stefanescu 4
7 years ago Bogdan Stefanescu 3
7 years ago Bogdan Stefanescu 2
7 years ago Bogdan Stefanescu 1
History: Created by Bogdan Stefanescu