Configuration Templates

Nuxeo applications integrate a configuration templates system to ease configuration and maintenance of configuration files. Nuxeo comes with default templates which mainly provide database configurations, but the templates can be used for any configuration purpose.

Principles

Nuxeo templates should be used to deploy specific configurations on your Nuxeo environments. Typically, it deals with configurations not exposed in Nuxeo Studio or through the Nuxeo extension system like an Elasticsearch mapping.

• Default Nuxeo templates values shouldn't be directly edited: custom templates should be created if you need to update default values.
• For production deployment, the user customizations should be stored outside the server filesystem hierarchy.
• The common template file should be used if the configuration applies for all environments. Consequently, additional specific templates should be created for specific environment configuration.

Properly using that template system ensures your customization of Nuxeo exclusively resides in your nuxeo.conf, custom templates and plug-in modules.

Use Cases

Nuxeo templates allow you to provide a specific configuration layer to any Nuxeo environment in nuxeo.conf:

• nuxeo.templates=default,env-one
• nuxeo.templates=default,env-two
• nuxeo.templates=default,env-one,env-two

It is possible to enable one layer on a specific Nuxeo instance easily. In theory, all environments can share the configuration files and then update only the value of templates setting in the local nuxeo.conf.

For instance, users can create templates for development, pre-production, and production environments; each template will include a different set of XML contributions:

• Users and Group: To manage user and group authentication against different authentication systems.
• Database: To store connection properties for a specific database environment.
• Specific needs: To add any custom configuration, as you can add custom properties to the nuxeo.conf file.
• ...

Templates are located in the "templates" directory ($NUXEO_HOME/templates). To enable a configuration, such as database configuration, you need to indicate which template to use in the nuxeo.conf configuration file.

Default Nuxeo Templates

Here are the templates provided by default:

• common: Common template used by other templates
• custom: Sample custom templates. Of course, this template is empty by default. One should copy it outside $NUXEO_HOME and adapt to their needs. See related section below.
• default: default Nuxeo configuration template for test purpose
• docker: Template to be used in the Docker image to only append the server logs to the console, not to a server.log file. Also, see the page about Logs.
• docker-json: Same as the docker template but allows to append the console logs as JSON.
• https: (not recommended) Template to make the server listen to port 443 (HTTPS)
• mariadb: MariaDB configuration template (since Nuxeo FT 9.1; for older versions of Nuxeo the mysql template should be used)
• mariadb-quartz-cluster
• mongodb: MongoDB configuration template
• mssql: MS SQL Server configuration template
• mssql-quartz-cluster
• mysql: MySQL configuration template
• mysql-quartz-cluster
• oracle: Oracle configuration template
• oracle-quartz-cluster;
• postgresql: PostgreSQL configuration template
• postgresql-quartz-cluster

Technical Overview

A server is considered as already configured when it has a "config" directory. When the "config" directory doesn't exist, templates will be used to generate all configuration files (config and datasources).

The template files contain defined parameters such as ${sample.parameter}.

Values for parameters replacement are calculated this way:

• If nuxeo.conf does not define nuxeo.templates, then nuxeo.templates equals "default" (the deprecated parameter nuxeo.template is still read for backward compatibility).
• The ${nuxeo.templates} value is used for determining the chosen template(s).
• For each value "nuxeo.template" of ${nuxeo.templates} (comma separated values, relative to "templates/" directory or absolute path), the corresponding file templates/${nuxeo.template}/nuxeo.defaults is read for defining new default values and maybe including other templates which are recursively parsed.
• The file templates/nuxeo.defaults is read for default values not already defined.
• The file nuxeo.conf is read for custom values (overwriting default values).

Configuration files are then generated by this way:

• For each comma separated value of nuxeo.templates and nuxeo.template.includes, the files in the referenced templates are copied using the previously calculated values for replacing parameters.
• Every included template will potentially overwrite its precedents.

You may want the variable to be resolved at runtime instead. In that case you can escape the variable in the configuration file this way: $${variable} instead of ${variable}.

Use a Custom Configuration Template to Store Your Customized Configuration Files

The "custom" template folder allows you to add customization such as using multiple databases, configuring services, etc.

1. Add your own template files in templates/custom directory. You can use either existing or new parameters in these new template files.
2. From the Admin tab or by manually editing the nuxeo.conf file, set your parameters' values and set nuxeo.templates=custom. You can refer to custom templates directory with a relative path or to your own custom templates directory with an absolute path.
3. Edit custom/nuxeo.defaults and set nuxeo.template.includes parameter to define the list of existing templates to include (comma separated values); your custom template will be used at last. nuxeo.defaults files from included templates are also read.

In case you need multiple customizations, create multiple directories and reference them in a dedicated nuxeo.conf for each server.

Move Your Configuration out of the Server Directory Structure

The "custom" template folder is a sample configuration template that you can use as is but it is recommended to create your own configuration template named as you want and located outside of the Nuxeo server structure, along with your customized nuxeo.conf.

For instance, under Linux, you could setup:

• Configuration files (custom templates and nuxeo.conf) under /etc/

  /etc/nuxeo/
  ├── nuxeo.conf
  └── some-custom-template

• Data under /var/lib/. It is common to also place the server itself under /var/lib/. Other common locations for the server are /opt/nuxeo/, ~nuxeo/nuxeo-cap-x.y-tomcat/...

  /var/lib/nuxeo/
  ├── data
  └── server (NUXEO_HOME)
      ├── conf
      ├── lib
      ├── nxserver
      ├── packages
      ├── templates
      ├── webapps
      └── work

• Log files under /var/log/

• PID files under /var/run/
• Temporary files under /tmp/