nuxeo · manonlumeau · Jan 19, 2021 · Jan 11, 2021 · Jan 11, 2021 · Jan 13, 2021
diff --git a/src/nxdoc/nuxeo-server/administration/internet-information-services-iis.md b/src/nxdoc/nuxeo-server/administration/internet-information-services-iis.md
@@ -2,7 +2,7 @@
 title: Internet Information Services (IIS)
 review:
     comment: ''
-    date: '2017-12-15'
+    date: '2021-01-18'
     status: ok
 labels:
     - content-review-lts2016
@@ -74,10 +74,10 @@ history:
         date: '2013-07-11 01:09'
         message: ''
         version: '1'
-
 ---
+
 {{! multiexcerpt name='internet-information-services-iis-content'}}
-This documentation gives you the guidelines to install a Nuxeo instance on a Windows Server and use IIS as a frontal web server. This documentation is more focused on the IIS configuration. For more details about the installation of the Nuxeo Platform or IIS, please refer to the relevant documentation.
+This documentation gives you the guidelines to install a Nuxeo instance on a Windows Server with the Tomcat server ZIP and use IIS as a frontal web server. This documentation is more focused on the IIS configuration. For more details about the installation of the Nuxeo Platform or IIS, please refer to the relevant documentation.
 
 Requirements:
 
@@ -90,11 +90,10 @@ Requirements:
 
 ### Nuxeo Installation
 
-1.  [Check Java is correctly installed]({{page page='installation#java-check'}}).
-2.  Download the [Nuxeo Windows distribution](http://www.nuxeo.com/downloads/) (.exe).
-3.  [Install the Nuxeo Platform]({{page page='installing-the-nuxeo-platform-on-windows'}}).
-4.  [Start the Nuxeo instance]({{page page='server-start-and-stop#start-windows'}}).
-5.  Open the Browser from the Windows Server (firewalls must be configured so as to allow this) at the address `http://NUXEO_SERVER/nuxeo`.
+1.  [Check Java is correctly installed]({{page page='tomcat-server-zip'}}#java-check).
+1.  [Install the Nuxeo Platform]({{page page='installing-the-nuxeo-platform-on-windows'}}).
+1.  [Start the Nuxeo instance]({{page page='server-start-and-stop'}}#start-windows).
+1.  Open the Browser from the Windows Server (firewalls must be configured so as to allow this) at the address `http://NUXEO_SERVER/nuxeo`.
 
 ### Enabling Web Server (IIS)
 

diff --git a/src/nxdoc/nuxeo-server/administration/setup-best-practices.md b/src/nxdoc/nuxeo-server/administration/setup-best-practices.md
@@ -3,7 +3,7 @@ title: Setup Best Practices
 description: Nuxeo applications come as ready-to-use applications that you can quickly install and evaluate. However, if you want to go to production, you may want to follow best practices.
 review:
   comment: ''
-  date: '2017-12-13'
+  date: '2021-01-18'
   status: ok
 labels:
   - content-review-lts2016
@@ -166,101 +166,44 @@ history:
     version: '1'
 ---
 
-Nuxeo applications come as ready-to-use applications, that you can quickly install and evaluate. However, if you plan to go in production, have several Nuxeo applications on the same machine or do some performance tests, here are some changes of configuration that we recommend to do, especially for advanced testing or before going into production.
-
-The steps given below are given using the [Admin tab]({{page page='admin-tab-overview'}}). They can of course also be done by [editing the `nuxeo.conf` file manually]({{page page='configuration-parameters-index-nuxeoconf'}}).
+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.
 
 ## Global Recommendation
 
 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]({{page page='configuration-parameters-index-nuxeoconf'}}), [the configuration templates]({{page page='configuration-templates'}}) and the [contributions]({{page page='how-to-contribute-to-an-extension'}}).
 
-## 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:**
-
-1.  Move the `nuxeo.conf` file from its default location.
-2.  After you moved `nuxeo.conf`, you need to [define its location as an environment variable](#nuxeo_conf).
-
-By default, `data` and `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:**
-
-{{{multiexcerpt name='JSF-UI-required' page='nxdoc/generic-multi-excerpts'}}}
-
-1.  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).
-2.  Click on **Save**.
-3.  Restart your server.
-    The `data` and `log` directories are created at the location you typed.
-
-**Data and log directories configuration**
+## Mounting Data, Log and Temporary Directories as Volumes
 
-<div class="table-scroll"><table class="hover"><tbody><tr><th colspan="1">
+{{#> callout type='info' }}
+The following recommendations are for the Nuxeo Docker image. If you are using [the Tomcat server ZIP](#tomcat-server-zip), please read the related section.
+{{/callout}}
 
-Field / Property
+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.
 
-</th><th colspan="1">
-
-Description
-
-</th></tr><tr><td colspan="1">
-
-Data directory
-`nuxeo.data.dir`
-
-</td><td colspan="1">
-
-Data directory (absolute or relative to NUXEO_HOME). It involves all data not being stored in the database.
-Linux recommended path: `/var/lib/nuxeo/...`
-
-</td></tr><tr><td colspan="1">
-
-Log directory
-`nuxeo.log.dir`
-
-</td><td colspan="1">
-
-Log directory (absolute or relative to NUXEO_HOME).
-Linux recommended path: `/var/log/nuxeo/...`
-
-</td></tr></tbody></table></div>
-
-## Defining Environment Variables {{> anchor 'define-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.
+Thus, the following directories should be mounted as external volumes in the container run from the Nuxeo Docker image:
 
-### `NUXEO_HOME`
-
-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/nuxeoctl` script (such as a service in `/ect/init.d`).
-
-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 `%PATH%`).
-- Linux and macOS X users will write `"export NUXEO_HOME=...`." in `~/.bashrc` or `~/.profile`.
-
-### `NUXEO_CONF`
+```shell
+/var/lib/nuxeo
+/var/log/nuxeo
+/tmp
+```
 
-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.
+For instance:
 
-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.
+```shell
+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.packages.nuxeo.com/nuxeo/nuxeo
+```
 
-#### Windows Specific Case
+## Add Configuration Properties
 
-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 `HKEY_LOCAL_MACHINE\SOFTWARE\%PRODNAME%\ConfigFile` with `%PRODNAME%` equals to "Nuxeo" (or in older versions, "Nuxeo CAP", "Nuxeo DM", "Nuxeo DAM", ...),
-- Environment variable `NUXEO_CONF`,
-- `"nuxeo.conf"` file in the working directory,
-- `"nuxeo.conf"` file on the Desktop,
-- `"nuxeo.conf"` file in the same location as `nuxeoctl.bat`.
+To add or update some configuration properties for the Nuxeo Platform, please read the related section about [nuxeo.conf]({{page page='configuration-parameters-index-nuxeoconf'}}#nuxeoconf-file).
 
 ## Changing the Default Embedded Database
 
@@ -274,8 +217,8 @@ Since Java 10, the JVM has better support for container environments. It offers
 They are respectively equivalent to the `Xms` and `Xmx` options, using a percentage of the Control Group memory limit (`cgroup`), the memory available for the Java process.
 The default values are:
 
-```
-InitialRAMPercentage = 1.5625
+```shell
+InitialRAMPercentage = 3
 MaxRAMPercentage = 25
 ```
 
@@ -287,7 +230,7 @@ Let's see how we satisfy this minimum `Xmx` requirement using the new options.
 
 By default, in `nuxeo.conf`, we define the following settings:
 
-```
+```properties
 JAVA_OPTS=-XX:InitialRAMPercentage=3 -XX:MaxRAMPercentage=25
 ```
 
@@ -313,20 +256,121 @@ When running in a Linux container, the JVM will automatically detect the `cgroup
 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 `Xms` and `Xmx`.
 
-```
+```properties
 JAVA_OPTS=-XX:InitialRAMPercentage=50 -XX:MaxRAMPercentage=50
 ```
 
+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:
+
+```shell
+docker run --name nuxeo \
+  -p 8080:8080 \
+  -e JAVA_OPTS=-XshowSettings:vm \
+  docker.packages.nuxeo.com/nuxeo/nuxeo
+```
+
 #### 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:
 
-```
+```properties
 JAVA_OPTS=-Xms1g -Xmx1g
 ```
 
+## 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:**
+
+1. Move the `nuxeo.conf` file from its default location.
+2. After you moved `nuxeo.conf`, you need to [define its location as an environment variable](#nuxeo_conf).
+
+By default, `data` and `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:**
+
+{{{multiexcerpt name='JSF-UI-required' page='generic-multi-excerpts'}}}
+
+1. 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).
+2. Click on **Save**.
+3. Restart your server.
+   The `data` and `log` directories are created at the location you typed.
+
+**Data and log directories configuration**
+
+<div class="table-scroll">
+  <table class="hover">
+    <tbody>
+      <tr>
+        <th colspan="1">Field / Property</th>
+        <th colspan="1">Description</th>
+      </tr>
+      <tr>
+        <td colspan="1">
+          Data directory<br/>
+          `nuxeo.data.dir`
+        </td>
+        <td colspan="1">
+          Data directory (absolute or relative to NUXEO_HOME). It involves all data not being stored in the database.<br/>
+          Linux recommended path: `/var/lib/nuxeo/...`
+        </td>
+      </tr>
+      <tr>
+        <td colspan="1">
+          Log directory<br/>
+          `nuxeo.log.dir`
+        </td>
+        <td colspan="1">
+          Log directory (absolute or relative to NUXEO_HOME).<br/>
+          Linux recommended path: `/var/log/nuxeo/...`
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+### Defining Environment Variables {{> anchor 'define-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.
+
+#### `NUXEO_HOME`
+
+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/nuxeoctl` script (such as a service in `/ect/init.d`).
+
+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 `%PATH%`).
+- Linux and macOS X users will write `"export NUXEO_HOME=...`." in `~/.bashrc` or `~/.profile`.
+
+#### `NUXEO_CONF`
+
+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 `HKEY_LOCAL_MACHINE\SOFTWARE\%PRODNAME%\ConfigFile` with `%PRODNAME%` equals to "Nuxeo" (or in older versions, "Nuxeo CAP", "Nuxeo DM", "Nuxeo DAM", ...),
+- Environment variable `NUXEO_CONF`,
+- `"nuxeo.conf"` file in the working directory,
+- `"nuxeo.conf"` file on the Desktop,
+- `"nuxeo.conf"` file in the same location as `nuxeoctl.bat`.
+
 &nbsp;
 
 ---

diff --git a/src/nxdoc/nuxeo-server/administration/variables-and-configuration.md b/src/nxdoc/nuxeo-server/administration/variables-and-configuration.md
@@ -2,7 +2,7 @@
 title: Variables and Configuration
 review:
     comment: ''
-    date: '2020-12-14'
+    date: '2021-01-14'
     status: ok
 tree_item_index: 90
 is_overview: true
@@ -20,7 +20,7 @@ Understand how variables are resolved in Nuxeo platform, and get a view on all o
 <br/>
 <br/>
 <br/>
-[Go&nbsp;<i class="fa fa-long-arrow-right" aria-hidden="true"></i>]({{page page='call-external-app-from-nuxeo'}})
+[Go&nbsp;<i class="fa fa-long-arrow-right" aria-hidden="true"></i>]({{page page='variables-and-configuration-pattern'}})
 {{/panel}}
 </div>
 <div class="column medium-4">
@@ -30,7 +30,7 @@ Understand how variables are resolved in Nuxeo platform, and get a view on all o
 Nuxeo Platform reads configuration properties in the `nuxeo.conf` file. Those parameters can be either environment parameters used by Nuxeo runtime or template parameters used for values replacement in configuration files.
 <br/>
 <br/>
-[Go&nbsp;<i class="fa fa-long-arrow-right" aria-hidden="true"></i>]({{page page='call-nuxeo-from-external-app'}})
+[Go&nbsp;<i class="fa fa-long-arrow-right" aria-hidden="true"></i>]({{page page='configuration-parameters-index-nuxeoconf'}})
 {{/panel}}
 </div>
 <div class="column medium-4">
@@ -44,7 +44,7 @@ Nuxeo applications integrate a configuration templates system to ease configurat
 <br/>
 <br/>
 <br/>
-[Go&nbsp;<i class="fa fa-long-arrow-right" aria-hidden="true"></i>]({{page page='call-nuxeo-from-external-app'}})
+[Go&nbsp;<i class="fa fa-long-arrow-right" aria-hidden="true"></i>]({{page page='configuration-templates'}})
 {{/panel}}
 </div>
 </div>