Rules for Distributions

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:

• in a zip named nuxeo-distribution-tomcat-5.4.2-nuxeo-dm.zip (Maven artifact org.nuxeo.ecm.distribution:nuxeo-distribution-tomcat:5.4.2:nuxeo-dm:zip) and uploaded as nuxeo-dm-5.4.2-tomcat.zip (downloadable ZIP)
• containing a folder named nuxeo-dm-5.4.2-tomcat

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").

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.