Home > Installation and Administration > Setup > Advanced Configuration > How to Create a Nuxeo Static WAR
Installation and Administration

How to Create a Nuxeo Static WAR

Updated: July 17, 2023

Creating a static WAR of Nuxeo allows you to deploy Nuxeo in an environment where your application server only allows WAR installation. Keep in mind that when you do this, the following dynamic features will not work (we are inside a static WAR):

  • Nuxeo Studio hot reload
  • Nuxeo IDE hot reload
  • Nuxeo Marketplace integration (hotfixes and packages installation)

Those limitations implies that if you want to change the distribution (for instance install or upgrade some Nuxeo Packages, change the configuration...), you must replay the following procedure and deploy the WAR newly generated.

How not to hardcode some properties

It is possible to keep some "dynamic" aspect on some parameters by giving them a variable as value: for instance, nuxeo.db.host=${custom.nuxeo.db.host} Then, you can use the produced Nuxeo WAR in an environment where custom.nuxeo.db.host is defined from outside.

 

Creating a Nuxeo Static WAR Distribution

Here is the way to create your own static WAR distribution:

  1. Download a Nuxeo Tomcat distribution.
  2. Unzip it in somewhere (let's call it $NUXEO_HOME).

  3. Customize and configure your application as usual:

    1. Deploy some Nuxeo Packages.
    2. Create your own configuration templates.
    3. Configure nuxeo.conf .

    4. Copy your specific bundles into $NUXEO_HOME/nxserver/bundles/.

      Such a practice is not recommended: you should deploy Nuxeo Bundles via a Nuxeo Package or, at least, via a custom configuration template

  4. Start the server.
  5. Check that your Nuxeo is configured as expected (database configuration, LDAP authentication, etc.).
  6. Stop the server.

  7. Launch this following command:

    $NUXEO_HOME/bin/nuxeoctl pack /tmp/nuxeo-war.zip

    Your static WAR distribution will be generated into /tmp/nuxeo-war.zip.

The generated ZIP contains what needs to be copied over a standard Tomcat installation:

nuxeo-war.zip/
|-- endorsed (jaxb and jaxws api libs that should replace packages provided by default JDK that are outdated)
|-- lib (common libs)
|-- README-NUXEO.txt
`-- webapps
    `-- nuxeo (exploded WAR that you can zip if needed)

Installing Nuxeo in the Target Tomcat

The distribution is mainly an overlay to be extracted at the root of your Tomcat instance.

You must provide the Nuxeo logs path and start the Catalina with more memory than its defaults; for instance:

# Usually set in bin/catalina.sh rather than export
export JAVA_OPTS="$JAVA_OPTS -Dnuxeo.log.dir=logs"
export CATALINA_OPTS="$CATALINA_OPTS -Xms512m -Xmx1024m -XX:MaxPermSize=512m"
./bin/catalina.sh start

The target database will be the one you defined in your source Nuxeo instance, and the default for the Nuxeo directories are:

  • nuxeo.config.dir : WEB-INF directory,
  • nuxeo.runtime.home : $TOMCAT_HOME/nuxeo,
  • nuxeo.data.dir : $TOMCAT_HOME/nuxeo/data,
  • nuxeo.tmp.dir : $TOMCAT_HOME/nuxeo/tmp,
  • nuxeo.web.dir : $TOMCAT_HOME/nuxeo/web (for WebEngine modules).

See Configuration Parameters Index (nuxeo.conf) for more details about these config parameters of the Nuxeo Platform.

If you need to change the values for these paths, setting System properties is not enough: you must add context-param entries in the Nuxeo WEB-INF/web.xml file (see JavaDoc of NuxeoStarter for more details).

Installing Nuxeo in the Target WildFly

The webapp/nuxeo folder content should be installed in your deployment profile  (i.e.: standalone/deployment/nuxeo.war). You should then augment the Nuxeo webapp libraries (i.e.: WEB-INF/lib) by the lib/ and endorsed/ folders content.

The target database will be the one you defined in your source Nuxeo instance, and the default for the Nuxeo directories are:

  • nuxeo.config.dir : WEB-INF directory,
  • nuxeo.runtime.home : $WILDFLY_HOME/nuxeo,
  • nuxeo.data.dir : $WILDFLY_HOME/nuxeo/data,
  • nuxeo.tmp.dir : $WILDFLY_HOME/nuxeo/tmp,
  • nuxeo.web.dir : $WILDFLY_HOME/nuxeo/web (for WebEngine modules).

See Configuration Parameters Index (nuxeo.conf) for more details about these config parameters of Nuxeo.

If you need to change the values for these paths, setting System properties is not enough: you must add context-param entries in the Nuxeo WEB-INF/web.xml file (see JavaDoc of NuxeoStarter for more details).

Upgrade or Install HotFix

Because of the limitations implied by the static WAR, you must generate a new WAR if you want to upgrade the server or apply some hotfix.