Understanding Bundles Deployment

Updated: March 18, 2024

Deployment Phases


The Nuxeo Platform deployment is incremental: the startup process involves different processors for different phases.

  1. Template processor for configuration
  2. Deployment-fragment pre-processor
  3. Bundle activation and deployment
  4. WAR/EAR deployment

Template Processor

The template system allows to use template for generating configuration files:

  • data source declaration
  • JCA connector declaration
  • SMTP Gateway
  • monitoring extensions
  • misc extension point contributions (LDAP, SMTP,

The template processor system uses Java property files to read the variable and do the replacement in the template to generate the actual configuration files.

The template processor system contains a profile system so that a given server can quickly be reconfigured for a target environment:

  • Dev profile
  • Integration profile
  • Production profile

The template system uses Freemarker so that template can contain simple conditional processing.

<extension target="org.nuxeo.ecm.core.repository.RepositoryService"
    <repository name="default"
      <repository name="default">
        <pool minPoolSize="${nuxeo.vcs["min-pool-size"]}" maxPoolSize="${nuxeo.vcs["max-pool-size"]}"
          blockingTimeoutMillis="100" idleTimeoutMinutes="10" />
<#if "${nuxeo.core.binarymanager}" != "" >
        <binaryManager class="${nuxeo.core.binarymanager}" />
        <clustering enabled="${repository.clustering.enabled}" delay="${repository.clustering.delay}" />
        <binaryStore path="${}" />

Deployment Fragment Preprocessor

In Nuxeo, the target web application is in fact created from a lot of separated bundles.

For that each bundle can contribute :

  • resources to the WAR
  • declaration in the web.xml
  • declaration in the faces-config.xml
  • Java property files for i18n

Because in JEE5 there is no standard way to do that, we use a pre-deployment processor that will process the bundles for deployment-fragment.xml files.

The deployment fragment contains ANT like commands that will be executed in order to contribute bundle resources to the JEE WAR Archive.

<extension target="pages#PAGES">
    <!-- Bind url to start the download -->
    <page view-id="/nxconnectDownload.xhtml"
      action="#{externalLinkManager.startDownload()}" />

  <extension target="faces-config#NAVIGATION">
      <redirect />

  <extension target="web#STD-AUTH-FILTER">

Bundle Deployment

This phase is the real deployment “à la OSGi” :

  • activate bundles
  • declare components, services and extension points
  • resolve Extension Point contributions

Standard WAR/EAR Deployment

The standard WAR deployment is managed by the host application server that will handle:

  • Web resource declaration (using the aggregated descriptor generated by the pre-deployment)
  • JSF initialization
  • Seam Init


NuxeoCtl is not really part of the deployment, but it's a central tool that helps managing Nuxeo Startup.

NuxeoCtl provides

  • a Nuxeo Bootstrap
    • runs template system
    • starts the target Application Server
  • some administration tools
    • Nuxeo Package administration and installation
    • start/stop/restart/configure …
  • a simple command GUI

NuxeoCtl, like the Templating System, is not really needed to be able to run Nuxeo. It just helps having a simple and efficient configuration.

It will be more and more true as we continue integrating features inside NuxeoCtl :

  • multi-node commands (like update package on each node)
  • cloud commands

In a sense, NuxeoCtl is close to what is provided in several “Cloud packaged tomcats” (TcServer, CloudFoundry …).

Existing Deployment Targets

Nuxeo Platform currently supports several deployment targets.

  Testing (Junit) Custom Tomcat/JBoss (dynamic mode) Tomcat WAR (static mode) Jboss EAR (static mode)
NuxeoCtl Not used Yes No No
Config templating Not used Yes Run once (before creating the WAR) Run once (before creating the EAR)
Pre-deployment Not used Started by custom deployer Run once (before creating the WAR) Run once (before creating the EAR)
Bundle activation Yes via Junit Started by custom deployer Started by Servlet listener Started by Jboss EAR listener
Standard deployment Not used Yes Yes Yes
Full deployment No JSF / WAR Yes Yes Yes
Marketplace feature N/A Yes No No

Depending on the target platform:

  • all deployment phases may not be run
  • platform features may change

The static deployment model was added initially for JBoss and was then extended to Tomcat too.

In the static deployment model NuxeoCtl pack command is run to:

  • run the template system
  • run the pre-processing
  • reorganize the WAR/EAR structure
  • add a activator to start the Bundle deployment
  • zip everything