Nuxeo applications come as ready-to-use applications, that you can quickly install and evaluate. However, if you plan to go in production, here are some changes of configuration that we recommend to do.
Nuxeo is designed by and for customization and extensibility: it is never required to edit a Nuxeo file, thus it should never be done. Following that principle will greatly ease the maintenance.
You must never edit the content of the server but use the configuration properties, the configuration templates and the contributions.
Mounting Data, Log and Temporary Directories as Volumes
Any data written by Nuxeo should be stored outside the container run from the Nuxeo Docker image. This ensures that the data is persisted and independent from the container that could be killed and removed at any time. It also eases backups and upgrades.
Thus, the following directories should be mounted as external volumes in the container run from the Nuxeo Docker image:
/var/lib/nuxeo /var/log/nuxeo /tmp
docker run --name nuxeo \ -p 8080:8080 \ -v /path/to/nuxeo/data:/var/lib/nuxeo \ -v /path/to/nuxeo/log:/var/log/nuxeo \ -v /path/to/tmp:/tmp \ docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021
Add Configuration Properties
To add or update some configuration properties for the Nuxeo Platform, please read the related section about nuxeo.conf.
Changing the Default Embedded Database
The Nuxeo Platform provides a default embedded database for testing and evaluation purpose, called H2. However, it is not adapted for a production environment (see the H2 limitations page).
Before going live, you should configure one of the production-safe database supported by the Nuxeo Platform. See the Database section of this documentation.
Java Virtual Machine Settings
Since Java 10, the JVM has better support for container environments. It offers some new options to control the JVM heap size:
They are respectively equivalent to the
Xmx options, using a percentage of the Control Group memory limit (
cgroup), the memory available for the Java process.
The default values are:
InitialRAMPercentage = 3 MaxRAMPercentage = 25
The historical requirements for Nuxeo are
Let's see how we satisfy this minimum
Xmx requirement using the new options.
By default, in
nuxeo.conf, we define the following settings:
By setting the minimum and maximum heap size to respectively 3% and 25% of the available memory, we get the following equivalent of the
|4 GB||128 MB||1 GB|
|8 GB||256 MB||2 GB|
|16 GB||512 MB||4 GB|
|32 GB||1 GB||8 GB|
Therefore, a server or container with 4 GB of memory satisfies the 1 GB minimum heap size.
In production, it is recommended to have the minimum heap size equal to the maximum heap size. This way, the JVM doesn't have to expand the heap size at runtime, which is more efficient and prevents possible out of memory errors.
When running in a Linux container, the JVM will automatically detect the
cgroup memory limit with the
UseContainerSupport option, enabled by default.
By default, the Nuxeo Docker image overrides the
JAVA_OPTS property in
nuxeo.conf to set the heap size to a fixed size, equal to 50% of the
cgroup memory limit.
This is achieved by using the same percentage for
InitialRAM as for
MaxRAM, resulting in equal
You can override or add some JVM setting by passing the
JAVA_OPTS environment variable to the Nuxeo Docker image.
For instance, to make the Nuxeo Launcher display the JVM settings in the console, run:
docker run --name nuxeo \ -p 8080:8080 \ -e JAVA_OPTS=-XshowSettings:vm \ docker-private.packages.nuxeo.com/nuxeo/nuxeo:2021
Non Container Environment
You can either:
- Use the same settings as for a container environment.
- Choose the exact heap size with, at the very least:
Tomcat Server ZIP
Moving Configuration, data and log Directories Outside Nuxeo
The configuration of your application is saved in the
nuxeo.conf configuration file, whatever the means you use to configure your application (manual edit or Admin tab). It is better, although not mandatory, to store your customized configuration outside the Nuxeo Platform. This way, you will be able to easily upgrade the Nuxeo Platform, keeping your configuration safely apart of Nuxeo directory.
To move the configuration file outside the Nuxeo directory:
- Move the
nuxeo.conffile from its default location.
- After you moved
nuxeo.conf, you need to define its location as an environment variable.
log directories are stored inside the Nuxeo tree. To ease backup and upgrades, it is highly recommended to move them outside the Nuxeo tree.
To move the data and log directories:
- In the Admin tab System Information > Setup tab, type the path to the location where you want the directories to be stored (see the table below).
- Click on Save.
- Restart your server.
logdirectories are created at the location you typed.
Data and log directories configuration
|Field / Property||Description|
Data directory (absolute or relative to NUXEO_HOME). It involves all data not being stored in the database.
Linux recommended path:
Log directory (absolute or relative to NUXEO_HOME).
Linux recommended path:
Defining Environment Variables
When the server starts, it guesses where the Nuxeo home directory and the Nuxeo configuration file (
nuxeo.conf) are located. If it doesn't find it or if you want to force it to use a specific home directory and/or a specific configuration file, you can define their location as environment variables.
Here is how Nuxeo home is guessed when the server starts: If
NUXEO_HOME is not set, then we use the parent of the directory
nuxeoctl is launched from.
Setting the Nuxeo home directory as an environment variable is recommended in the following cases:
- if you installed several Nuxeo applications on the same machine (for evaluation or production purpose),
- if you want to use other scripts than the
$NUXEO_HOME/bin/nuxeoctlscript (such as a service in
You must then set
NUXEO_HOME=/path/to/nuxeo in the system environment variables:
- Windows users must write
"set NUXEO_HOME=..."or use the control panel interface to define user environment parameters (like it's done for
- Linux and macOS X users will write
"export NUXEO_HOME=...." in
You need to set the location of the
nuxeo.conf file as an environment variable if you moved your configuration outside of the Nuxeo directory.
Moving the data and configuration outside the Nuxeo directory is recommended in a production environment because it makes upgrades easier and more secured: Your data and configuration won't risk to be overridden or lost. You must then set
NUXEO_CONF=/path/to/nuxeo.conf in the system environment variables.
Windows Specific Case
Under Windows, the location of the
nuxeo.conf is defined by that order of priority (i.e. first one of those found is used):
- Registry key
%PRODNAME%equals to "Nuxeo" (or in older versions, "Nuxeo CAP", "Nuxeo DM", "Nuxeo DAM", ...),
- Environment variable
"nuxeo.conf"file in the working directory,
"nuxeo.conf"file on the Desktop,
"nuxeo.conf"file in the same location as