Configuration

Microsoft Office configuration

For Windows server with Microsoft Office ONLY

If you chose to use Microsoft Office with ARender, please follow the below instructions:

Download and execute the following zip file and execute runCheck.bat: AromsCheck

Download and install the below softwares:

Create the below system folder:

  • C:\Windows\System32\config\systemprofile\Desktop

  • C:\Windows\SysWOW64\config\systemprofile\Desktop

Warning
  • Launch the rendition using a local account - Administrator or not - (Services > ARender Rendition Service > Log On) that opens Microsoft Office without any issues nor without pop-ups. Pop-ups will hinder the piloted mode of Microsoft Office and will block the rendering process of the rendition server.
  • In order to configure Excel file conversion, please check that the user launching Excel has also a default printer configured (as an example, the default printer that outputs XPS files) otherwise Excel won’t be able to do its work on pageSetup and won’t convert the documents.
  • Please do not use as default printer the printer that is forwarded, this is a printer that is only here during remote desktop session and will stop working as soon as you leave the server

Microsoft Office properties configuration in ARender

It is possible to configure the rendering of Office documents. To do so, modify the file aroms.properties located in the folder: modules\TaskConversion\aroms2pdf of the Rendition installation.

Below the available properties:

Properties Default value Detail
PDF/A false PDFs generated by ARender through MS Office are a PDF/A
processAutoKill false Clean old MS Office processes at Aroms start
TimeoutS 120 Maximum time that ARender takes to generates the PDF with MS Office. After that, conversion is aborted
AromsHost http://localhost:8000/ URL on which ARender Aroms is exposed
LockFields false Disable the auto-update of variable field (like a date field)
IgnorePrintAreas true Disable the print of empty lines
FitSheetOnOnePage true True: MS Office will try to print the document in one PDF page. False: MS Office default behavior (split if too much pages)

Cache and disk space configuration

Hazelcast

With the 4.5 version of ARender Hazelcast can be used in ARender to share the cache between all Rendition servers, if and only if, the cache directory is shared between the renditions.

You can find the complete documentation on the Hazelcast site.

Details on the hazelcast default configuration

The configuration file for Hazelcast is located on the rendition side in the document-service-broker resources. The path to find the configuration is ARender-Rendition-2023.X.Y\modules\RenditionEngine\rendition-engine-micro-service-2023.X.Y.jar\BOOT-INF\classes\hazelcast.yaml.

Default file: hazelcast.yaml
hazelcast:
  map:
    documentAccessors:
      max-idle-seconds: 3600
      eviction:
        eviction-policy: NONE
        max-size-policy: PER_NODE
        size: 5
  network:
    join:
      auto-detection:
        enabled: false
    rest-api:
      enabled: true
      endpoint-groups:
        CLUSTER_READ:
          enabled: true
        HEALTH_CHECK:
          enabled: true
        WAN:
          enabled: true
        DATA:
          enabled: true

Property Description
max-idle-seconds This property is used to define the time when the document is kept in the cache. This value is in seconds. By default, a document is cached for 1 hour, so the default is 3600. You can find more details on related Hazelcast documentation.
eviction-policy This property is used to define the eviction policy for cached documents when the maximum cache value is exceeded. By default, the value is NONE which corresponds to no eviction and that the maximum size is ignored. You can find more details on related Hazelcast documentation.
max-size-policy This property defines how Hazelcast will calculate the maximum cache size. By default the value is PER_NODE which defines that the maximum cache size is applied for each member of the cluster. You can find more details on related Hazelcast documentation.
size This property defines the maximum size of the cache. By default the value is 5. You can find more details on related Hazelcast documentation.
network.join.auto-detection This property is used to define the Hazelcast detection mechanism for members of a cluster on the same network. By default the value is false. You can find more details on related Hazelcast documentation.

Cleaning the temporary directory at startup

Although evicting an entry in the hazelcast cache leads to the deletion of the document in the cache, it is also possible to configure a deletion of cache directories when launching the application.

Configuration

The property default.document.path.startup.clear can be set to true to launch a deletion of cache directories on the application startup.

modules\RenditionEngine\application.properties
default.document.path.startup.clear=true

By default, this leads to the deletion of all folders created more than a day ago, however this value can be changed with the following configuration:

application.yaml
temp:
  files:
    folder: ../../tmp/
    house-keeping:
      expiration:
        time: 1
        unit: DAYS

Property Description
time The numerical time value
unit The time unit associated, which can be “SECONDS”, “MINUTES”, “HOURS” and “DAYS”

rest-api

The REST API is enabled by default with the enabled: true property. You can find more details on related Hazelcast documentation.

endpoint-groups

This section allows you to define the endpoint groups that can be used with the REST API. You can find more details on related Hazelcast documentation.

CLUSTER_READ

Allows access to the following endpoints :

  • /hazelcast/rest/cluster
  • /hazelcast/rest/management/cluster/state
  • /hazelcast/rest/license (GET)
  • /hazelcast/rest/management/cluster/version (GET)
  • /hazelcast/rest/management/cluster/nodes
  • /hazelcast/rest/instance
  • /hazelcast/rest/log-level (GET)
HEALTH_CHECK

Allows access to the following endpoints :

  • /hazelcast/health/node-state
  • /hazelcast/health/cluster-state
  • /hazelcast/health/cluster-safe
  • /hazelcast/health/migration-queue-size
  • /hazelcast/health/cluster-size
  • /hazelcast/health/ready

Have custom configuration

To customize the Hazelcast configuration, you will need to create your own hazelcast.yaml file and copy the configuration from the file ARender-Rendition-4.X.Y\modules\RenditionEngine\rendition-engine-micro-service-4.X.Y.jar\BOOT-INF\classes\hazelcast.yaml.

Version upgrade
For each upgrade of ARender, please read the release note carefully to take into account potential changes to the initial configuration.

After making your own configuration file, you will need to modify the custom-setenv.bat file or the custom-setenv.sh file in order to specify the path of the new file to use. To do this, you must add the -Dhazelcast.config = argument to the list of JVM arguments. By default, if the path specified is hazelcast.yaml then the path where the file should be placed is ARender-Rendition-4.X.Y\modules\RenditionEngine.

custom-setenv.bat
set ARENDER_BROKER_JVM_ARGS=-Djava.net.preferIPv4Stack=true -Djava.net.preferIPv6Addresses=false -Dloader.path="client_libs/" -Dfile.encoding=UTF-8 -Dhazelcast.config=hazelcast.yaml

Cache directory not shared between multiple renditions

Disable detection of each instance

You must disable the property, seen previously, of auto-detection. This property is disabled by default.

Configurate the Web-UI

You must specify each host of each rendition in the Web-UI server configuration. The distribution will be made by the Web-UI according to the weather of the renditions.

Configuration details can be found on the dedicated page.

Cache directory shared between several renditions

Hazelcast port opening

By default, the port for Hazelcast is 5701. For communication between machines, you must open the hazelcast port for each rendition.

Enable detection of each instance

You must activate the property, seen previously, of auto-detection which allows Hazelcast to know each instance of rendition.

Location of rendition instances

Each rendition must be placed in the same sub-network to allow cache directory sharing.

Configure the shared directory

In the context of using Hazelcast with a multi-instance of rendition and a shared directory, you will necessarily need the shared directory to be in NFS .

For each microservice of each rendition instance, it is necessary to specify the location of the shared cache directory that will be used. The property is located in the application.yaml file for each microservice.


temp:
  files:
    folder: ../../tmp/


shared-files:
  sharedPath: ../../tmp/


shared-files:
  sharedPath: ../../tmp/


tmp:
  dir:
    doc: ../../tmp/

shared-files:
  sharedPath: ../../tmp/

Configure the Web-UI with Load balancer

In case you have a Load balancer between the Web-UI and the renditions, you will have to indicate, in the configuration of the Web-UI server, the host of the Load balancer instead of listing the hosts of each rendition.

arender-server-custom-vanilla.properties

arender.server.rendition.hosts=LOAD_BALANCER_HOST

Configuration details can be found on the dedicated page.

Configure the Web-UI without Load balancer

If you do not have a Load balancer between the Web-UI and the renditions, you must indicate, in the configuration of the Web-UI server, each host of each rendition. The distribution will be made by the Web-UI according to the weather of the renditions.

Configuration details can be found on the dedicated page.

Use in AWS

In an AWS environment, if an instance describe based on a tag needs to be done then it must be ensured that the role attached to the EC2 instance has the right to describe the instance.

Configure NFS

NFS configuration is important to ensure that different nodes are in sync with each other.
Two main optimization configurations in NFS involve a high risk of NFS clients getting out of sync:

  • Asynchronous writing (async option), set by default
  • The local read cache (lookupcache or FS-Cache, fsc option) NFS requirements should contain the following options to ensure client synchronization :

sync,noac,lookupcache=none

References :
nfs(5) - Linux man page 10.3
NFS Red Hat Enterprise Linux 6