Nuxeo Core Developer Guide

Rules for Distributions

Updated: October 22, 2018 Page Information Edit on GitHub

Files and Directories Naming

The common rule is to zip a folder containing the distribution with an explicit name giving the product name, the version and the server.

For instance, Nuxeo DM 5.4.2 with Tomcat will be packaged:

Corresponding installers will be named with a suffix: nuxeo-dm-5.4.2-tomcat-setup.exe, nuxeo-dm-5.4.2-tomcat-izpack-installer.jar, nuxeo-dm-5.4.2-tomcat-izpack-installer.exe, nuxeo-dm-5.4.2-tomcat-izpack-installer.app.zip, ...

Distribution Specifics

Some information needs to be set at distribution build time.

Distribution Properties

For marketplace needs, all products need to be identified (NXP-5903).

Every assembly.xml creating a distribution must do the following:

  • Add a tstamp call in assembly initialization:

    <target name="init" unless="init.done">
        <tstamp />
        ...
        <antcall target="expand" />
        <property name="init.done" value="true" />
    </target>
    
  • Add a set-distribution-properties target:

    <target name="set-distribution-properties">
        <echo append="false" file="${distribution.properties.file}">## DO NOT MANUALLY EDIT THIS FILE
    org.nuxeo.distribution.name=${org.nuxeo.distribution.name}
    org.nuxeo.distribution.server=${org.nuxeo.distribution.server}
    org.nuxeo.distribution.version=${org.nuxeo.distribution.version}
    org.nuxeo.distribution.date=${org.nuxeo.distribution.date}
        </echo>
    </target>
    
  • Just before zip and attach:artifact, do

    <antcall target="set-distribution-properties">
        <param name="distribution.properties.file" value="${distribution.dir}/templates/common/config/distribution.properties" />
        <param name="org.nuxeo.distribution.name" value="dm" />
        <param name="org.nuxeo.distribution.server" value="jboss"/>
        <param name="org.nuxeo.distribution.version" value="${maven.project.version}" />
        <param name="org.nuxeo.distribution.date" value="${DSTAMP}${TSTAMP}"/>
    </antcall>
    

Properties' values:

  • org.nuxeo.distribution.name: cap, dm, dam, cmf, coreserver, correspondence, ...
  • org.nuxeo.distribution.server: jboss, tomcat, jetty, ...
  • org.nuxeo.distribution.version is the product version: 5.4.0-SNAPSHOT, 5.4.0, 1.0, 1.1-SNAPSHOT, ...

These values are used by Connect and Studio when registering an instance through Connect, and must be chosen among values legal for Connect/Studio. TODO document what vocabularies or enum they follow.

Default Values

Some values needed by the configuration templates depend on the distribution (for instance the product name).

Add the following just after the set-distribution-properties call:

<echo append="true" file="${distribution.dir}/templates/nuxeo.defaults">
org.nuxeo.ecm.product.name=Product Name
</echo>

Replace "Product Name" with the relevant one (for instance "Nuxeo DM").

Nuxeo IDE Requirements

Since Nuxeo 5.4.3, Nuxeo IDE can use a distribution as a SDK provided the following requirements:

  • There must be a "sdk" directory at root of the distribution containing:
    • distribution.properties file,
    • artifacts-*.properties file,
    • test-artifacts-*.properties file.
  • Optionally, there may be a "sdk/tests" directory at root of the distribution containing the test artifacts.
  • Optionally, there may be a "sdk/sources" directory at root of the distribution containing the sources artifacts. Source artifacts will be downloaded for released distributions only.

Nuxeo IDE is being replaced by the Nuxeo Generator and won’t be maintained any longer. You can take a look at the page Configure Nuxeo Platform to discover how to use the Nuxeo Generator.

Here are code snippets for assemblies (require nuxeo-distribution-tools 1.10.2 or, since Nuxeo 5.9.2, ant-assembly-maven-plugin2.0); new lines start with "+":

Generate artifacts-coreserver.properties and test-artifacts-coreserver.properties files in nuxeo-distribution-coreserver

<target name="expand">
+ <artifact:nuxeo-expand scope="test" />
+ <artifact:print output="${outdir}/test-artifacts-coreserver.properties" mode="sdk" />
  <artifact:nuxeo-expand />
+ <artifact:print output="${outdir}/artifacts-coreserver.properties" mode="sdk" />
</target>

<target name="build-standard" description="Build default distribution" depends="init">
  (...)
+ <copy file="${outdir}/artifacts-coreserver.properties" todir="${nuxeo.ear}" />
+ <copy file="${outdir}/test-artifacts-coreserver.properties" todir="${nuxeo.ear}" />
  <zip destfile="${outdir}/${maven.project.artifactId}-${maven.project.version}.zip" basedir="${nuxeo.ear}" />
  <artifact:attach file="${outdir}/${maven.project.artifactId}-${maven.project.version}.zip" target="${maven.project.groupId}:${maven.project.artifactId}" type="zip" />
</target>

Generate sdk directory in nuxeo-distribution-tomcat

<target name="init" unless="init.done">
  (...)
+ <condition property="build.sdk">
+   <or>
+     <isset property="maven.profile.release" />
+     <isset property="maven.profile.sdk" />
+   </or>
+ </condition>
  (...)
</target>

<target name="expand" unless="no.build">
  <artifact:nuxeo-expand />
+ <artifact:print output="${outdir}/artifacts-tomcat.properties" mode="sdk" />
</target>

<target name="reorganize-libs-zip-attach">
  <antcall target="reorganize-libs" />
+ <antcall target="copy-sdk-resources" />
  <zip destfile="${outdir}/${maven.project.artifactId}-${maven.project.version}-${classifier}.zip" basedir="${outdir}" includes="${classifier}-${maven.project.version}-tomcat/**" />
  <artifact:attach file="${outdir}/${maven.project.artifactId}-${maven.project.version}-${classifier}.zip" target="${maven.project.groupId}:${maven.project.artifactId}" classifier="${classifier}" type="zip" />
+ <antcall target="build-sdk" />
</target>

+ <target name="copy-sdk-resources">
+   <copy file="${outdir}/artifacts-tomcat.properties"
+         todir="${distribution.dir}/sdk" />
+   <move todir="${distribution.dir}/sdk">
+     <fileset dir="${distribution.dir}/nxserver/">
+       <filename name="*artifacts-*.properties" />
+     </fileset>
+   </move>
+ </target>

+ <target name="build-sdk" if="build.sdk">
+   <mkdir dir="${distribution.dir}/sdk/sources" />
+   <copy todir="${distribution.dir}/sdk/sources">
+     <artifact:resolveFiles source="${distribution.dir}/sdk/artifacts-*.properties" classifier="sources" />
+   </copy>
+   <mkdir dir="${distribution.dir}/sdk/tests" />
+   <copy todir="${distribution.dir}/sdk/tests">
+     <artifact:resolveFiles source="${distribution.dir}/sdk/test-artifacts-*.properties" />
+   </copy>
+   <zip destfile="${outdir}/${maven.project.artifactId}-${maven.project.version}-${classifier}-sdk.zip" basedir="${outdir}" includes="${classifier}-${maven.project.version}-tomcat/**" />
+   <artifact:attach file="${outdir}/${maven.project.artifactId}-${maven.project.version}-${classifier}-sdk.zip" target="${maven.project.groupId}:${maven.project.artifactId}" classifier="${classifier}-sdk" type="zip" />
+ </target>

Startup Wizard

Since Nuxeo EP 5.4.1 a startup wizard is available to help users configure their Nuxeo the first time it's started.

It starts in less than 2s and asks the user to enter the main configuration parameters (such as binding IP, logs and data directory), HTTP proxy, SGBD, SMTP and, in particular, offers easy registration to Nuxeo Studio and Connect.

It is currently only available for Tomcat distributions and will work with any Nuxeo product (DM, DAM and CMF have dedicated welcome message and logo; others are identified as "EP" products). If needed it can be made available in other distributions.

Technical requirements:

  • Startup wizard is managed by Nuxeo Launcher.
  • It is started if and only if

    • nuxeo.conf: nuxeo.force.generation is not false
    • nuxeo.conf: nuxeo.wizard.done=false, so please update your release procedure.
    • templates/nuxeo-wizard.war exists, so please add the following in your assembly file:

      <!-- Nuxeo wizard -->
      <copy tofile="${distribution.dir}/templates/nuxeo-wizard.war">
          <artifact:resolveFile key="org.nuxeo.ecm.distribution:nuxeo-startup-wizard:${nuxeo.distribution.version}:war" />
      </copy>
      
      

At the end of the wizard, a restart is called and the wizard will no more be ran unless the property nuxeo.wizard.done is reset to false.

By default, the startup wizard is not activated in order not to disturb developers and continuous integration but it must be properly installed in all distributions. It will be activated in all downloadable packages by adding the property nuxeo.wizard.done=false in nuxeo.conf.

As nuxeo.conf is used by the startup wizard, port translation is still available: multiple tomcat instances running on the same server will not conflict.

2 months ago manonlumeau NXDOC-1650 fix about integrating changes, add mention on multiple attempts
3 years ago Manon Lumeau 24
5 years ago Solen Guitter 23
5 years ago Julien Carsique 22
7 years ago Julien Carsique 21 | Migrated to Confluence 4.0
7 years ago Julien Carsique 20 | Reverted from v. 18
7 years ago Julien Carsique 19
7 years ago Julien Carsique 18 | NXP-7905 - Generate Nuxeo SDK resource per application
7 years ago Julien Carsique 17 | use nuxeo-distribution-tools:nuxeo-expand sdk mode
7 years ago Julien Carsique 16 | udpate SDK Ant targets snipets
7 years ago Julien Carsique 15
7 years ago Julien Carsique 14 | Nuxeo IDE requirements
7 years ago Florent Guillaume 13
7 years ago Julien Carsique 12 | add product name
7 years ago Julien Carsique 11
8 years ago Florent Guillaume 10
8 years ago Florent Guillaume 9
8 years ago Julien Carsique 8
8 years ago Julien Carsique 7 | startup wizard requirements
8 years ago Julien Carsique 6
8 years ago Julien Carsique 4
8 years ago Julien Carsique 5
8 years ago Julien Carsique 3
8 years ago Julien Carsique 2
8 years ago Julien Carsique 1
History: Created by Julien Carsique

We'd love to hear your thoughts!

All fields required