edoras one Operator Guide

1. Overview

This document describes the operational aspects of edoras one and its integration with other systems.

It is intended for system administrators responsible for configuring an edoras one installation.

2. Server Requirements

2.1. Java

The minimum Java version to run edoras one is 8.

If you use MySQL or MSSQL you need to set a case sensitive collation such that edoras one has the same functionality as on any other database. We recommend the following collation for MySQL and MSSQL:

MySQL collation: utf8_bin
Execute the following query to change it on your database: ALTER DATABASE {DATABASE-NAME} CHARACTER SET utf8 COLLATE utf8_bin;
MSSQL collation: Latin1_General_CS_AS
Execute the following query to change it on your database: ALTER DATABASE {DATABASE-NAME} COLLATE Latin1_General_CS_AS;

2.3. Fonts

The edoras one server requires a number of Microsoft TrueType fonts to be available to run correctly. On many systems the required fonts will already be installed by default, but in some cases this may not be the case. If the fonts are not available, the result may be a long wait while the server attempts to find the fonts somewhere in the filesystem and it may not be possible to start the server at all.

On Linux systems (e.g. CentOS) the required fonts can be obtained by installing the msttcorefonts package.

3. Tenant configuration

A new tenant in edoras one is created by adding a tenant definition file to the tenant data folder and restarting the server. The tenant data may either be built into the edoras one WAR file (see the :developer-guide: for more information) or placed in an external folder. The tenant data location can be configured using the system.tenant-cfg-location property. To use an external folder, the value of this property should have a file: prefix, for example:

file:${edoras-one.home}/tenants

3.1. Overall structure

The tenant definition is a JSON object definition, something like the following:

{
    "id": "tenantId",
    "name": "acme",
    "adminUserLogin": "testAdmin1",
    "adminUserEmail": "testAdmin@test.com",
    "accounts": [
        {
            "name": "account",
            "domain": "test.com",
            "cssClass": "account-blue",
            "groups": [ "group" ],
            "users": [
                {
                    "displayName": "John Smith",
                    "firstName": "John",
                    "lastName": "Smith",
                    "login": "john.smith",
                    "email": "john.smith@email.es",
                    "language": "en",
                    "memberGroups": ["group"]
                }
            ]
        }
    ]
}

The following sections describe the available attributes for each part of the definition.

3.2. Tenant information

The top level of the JSON contains information about the tenant. The following attributes are supported:

Table 1. Tenant attributes
Attribute name	Description
accounts	a list of the initial accounts
adminUserLogin	admin user’s login
adminUserEmail	admin user’s email address
name	tenant name

3.3. Account information

An account entry defines an initial account within the tenant. The following attributes are supported:

Table 2. Account attributes
Attribute name	Description
domain	domain name (used to create user email addresses automatically)
cssClass	account css class added to the html
groups	a list of group names
name	account name
users	a list of the initial account users

For each account entry, an account will be created with the given name, groups and users.

The CSS class will be used when any user that belongs to the account is logged in. Then this CSS class will be applied to the app div (.edoras-one).

For "Cloud" solutions, there are some predefined account CSS classes:

Table 3. Account predefined "Cloud" css classes and colours
CSS Class	Main Colour	Main Dark Colour
account-brown
account-green
account-teal
account-blue
account-purple
account-pink
(empty/default)

Leave CSS class empty to turn off UI customisation for the Account and use default colours.

3.4. User information

A user entry defines an initial user within the account. The following attributes are supported:

Table 4. User attributes
Attribute name	Description
displayName	user’s display name
firstName	user’s first name
lastName	user’s last name
login	user’s login
email	user’s email address
language	user’s language
memberGroups	groups that the user belongs to

For each user entry, a user will be created with the given information.

If no email address is provided and the account domain is set, then an email address will be created from the domain and user’s first and last names.

When defining a user’s group membership, both the default edoras one group names (edoras one Modeler etc.) and the group names explicitly defined in the account may be used.

4. Standard properties

edoras one provides a number of configuration properties that can be used to control the behaviour of the application. These properties can be set in a number of different ways:

in a property file built in to the application (this can only be changed by a developer)
in an external property file: one.properties
as a system property, for example on the application command line

These are listed in order of increasing precedence, so a property value defined by the application can be overwritten by an external property file, for example.

Properties are used to configure individual settings within edoras one’s Spring configuration. As an on-premise project may replace some or all of this Spring configuration, the properties that may be used in any given installation may also vary. The remainder of this section assumes that the installation uses the standard edoras one Spring configuration files.

4.1. Locating the external property file

edoras one looks for external property file in the edoras one configuration folder. By default this is the folder .edoras-one in the user’s home directory. An alternative configuration folder can be selected by setting the system property edoras-one.home.

If no external property file can be found then a message to that effect will be produced by edoras one during the application startup.

4.2. Basic configuration properties

Table 5. Basic properties
Property	Default value	Description
`edoras-one.home`	`${user.home}/.edoras-one`	the location of the edoras one configuration folder. This can only be set as a system property.
`system.application-endpoint`	`http://localhost:8080/one`	the base URL where the application is running
`system.license-location`	`file:${user.home}/.edorasware/edorasware.license`	the location of the edoras one license
`system.tenant-cfg-location`	`classpath:/com/edorasware/config/custom/tenant/.json`	the location of the tenant configuration files

4.2.1. Application endpoint

The system.application-endpoint property is used in several features of edoras one including the automatic email sender which sends an assigned task URL or the linked resource filter which is used to map constant front end resources names to hashed/versioned versions of these. This endpoint needs to be set to the endpoint where the clients are able to access edoras one. If the endpoint is set to https://edoras-one.com then the clients need to access it through this URL.

There are two setup methods on how you are able to access edoras one: first directly through the servlet container and second via a proxy. If you use the first option everything should work properly when you set the correct system.application-endpoint, but when you use the second option (behind a proxy) then you need to set the application .endpoint property to the endpoint of the proxy and not the one of the proxied servlet container.

If you have several endpoints accessing the same edoras one instance, then you need to ensure that the application.endpoint is set to one of these endpoints which is working correctly, but keep in mind that all generated URL’s will have this endpoint as prefix.

4.3. Content storage properties

Table 6. Content storage properties
Property	Default value	Description
`content.provider-type`	`database`	select the content persistence type (`file` or `database`)
`content.enable-versioning`	`false`	when set to `true`, the content manager will keep all the versions of the content on every update
`content.cache.folder`	`${edoras-one.home}/temp/converted-content`	the location for the on-disk content conversion cache

When file-based content persistence is used, the following properties may also be set:

Table 7. File-based content storage properties
Property	Default value	Description
`content.provider.file.root-folder`	none (REQUIRED)	the root folder for content persistence

4.4. App management properties

When the system is started, the system App from the product will be updated automatically (or installed if the system is being started for the first time). Apps from addons or the project will be also be installed if they are available.

When an App is imported, the version information from the new App will be compared against the version information of the App currently installed on the system. If the App on the system has changes that would be lost (for example the App has been locally edited) then the import will normally fail and the problem will be logged. The version check can be overridden by setting the appropriate force properties as described below.

Failure to update a pre-installed App will normally terminate the server startup with an error, as it is assumed that the Apps are critical to correct operation of the system. This behaviour can be overridden by setting the appropriate properties to ignore any errors, although this may mean that some Apps will not be updated in the running system.

The behaviour of the automatic App installation can be configured using the following properties:

Table 8. App management properties
Property	Default value	Description
`apps.import.addons-location`	`classpath:/com/edorasware/addons/app/.zip`	The location of pre-installed Apps from addons
`apps.import.custom-location`	`classpath:/com/edorasware/config/custom/app/.zip`	The location of pre-installed custom Apps
`apps.editable-system-app`	`false`	When `true`, allows system models to be seen and edited by everyone instead of just the supervisor
`apps.import.force-system-app`	`false`	Forces the import of the system App when `true`
`apps.import.force-addons-app`	`false`	Forces the import of Apps from addons when `true`
`apps.import.force-custom-app`	`false`	Forces the import of custom Apps when `true`
`apps.import.ignore-system-app-errors`	`false`	Ignore failures when importing the system App
`apps.import.ignore-addons-app-errors`	`false`	Ignore failures when importing Apps from addons
`apps.import.ignore-custom-app-errors`	`false`	Ignore failures when importing custom Apps

4.5. Clustering properties

The clustering support for edoras one can be enabled by setting the following properties:

Table 9. Clustering properties
Property	Default value	Description
`cluster.enable`	`false`	enables clustering support when set to `true`
`cluster.redis.hostname`	`localhost`	the hostname where the Redis server is running
`cluster.redis.port`	`6379`	the port where the Redis server is listening to incoming connections
`cluster.redis.password`	(empty)	the password of the Redis server

For more details on configuring an edoras one cluster please refer to the section on Clustering.

4.6. Query export properties

Table 10. Query export properties
Property	Default value	Description
`export.date.format`	`yyyy-MM-dd’T’HH:mm:ss.SSS’Z'`	the format to be used for exported dates (see SimpleDateFormat)
`export.date.timezone`	`UTC`	the timezone to be used for exported dates (see TimeZone)

4.7. Elasticsearch integration properties

The following properties can be used to configure the Elasticsearch integration so that it can connect to a suitable Elasticsearch cluster. When a property is not defined then the default value will be used. The settings currently in use are also shown in the server log on system startup.

Table 11. Elasticsearch integration properties
Property	Default value	Description
`search.elasticsearch.enable`	`false`	Enables the elasticsearch integration
`search.elasticsearch.cluster-name`	`edorasone`	the elasticsearch cluster name
`search.elasticsearch.node-addresses`	`127.0.0.1:9300`	a comma-separated list of network addresses that should be used to connect to an external cluster
`search.elasticsearch.failed-job-retries`	`3`	the number of retries for a failed indexing job before it is abandoned

4.8. Mail properties

The following properties can be used to configure the mail integration and several default mail models.

Table 12. Mail properties
Property	Default value	Description
`ui.support-mail`	`support@edorasware.com`	when a user clicks on the support button in the footer the local mail client will open with the specified mail address as 'to address'
`mail.smtp.host`	`smtp.office365.com`	the SMTP host. If this property is empty then mails will simply be logged and not sent.
`mail.smtp.port`	`587`	the SMTP port
`mail.smtp.username`	`no-reply@edorasware.com`	the SMTP user name for the authentication
`mail.smtp.password`	`*`	the SMTP password for the authentication
`mail.smtp.encoding`	`UTF-8`	the encoding used to send the mails over SMTP
`mail.smtp.debug`	`false`	true if SMTP debug log output should be written, false otherwise
`mail.smtp.transport-protocol`	`smtp`	the SMTP transport protocol
`mail.smtp.auth`	`true`	true if SMTP authenticates using the user name and password properties, false otherwise
`mail.smtp.enable-starttls`	`true`	true if SSL should be used to communicate with the SMTP server, false otherwise
`mail.smtp.from`	`no-reply@edorasware.com`	the From mail address to be used
`mail.test-recipient`	``	when set, all emails (of all users) are sent to this email address. WARNING: Only use this for testing purposes.
`mail.model.assignee-changed`	`MAIL_MODEL-ec56a716-36c7-4850-8081-5daa9912872f`	the model id (technically the global ID) of the mail model used to send notification emails if a work item is assigned to the user
`mail.model.candidate-groups-changed`	`MAIL_MODEL-499f4935-0987-46ba-ac1e-ba6632927f16`	the model id (technically the global ID) of the mail model used to send notification emails if a work item is created of which the user is a candidate user
`mail.model.work-object-edited`	`MAIL_MODEL-0252639c-df22-4d4e-9262-0890587c192f`	the model id (technically the global ID) of the mail model used to send notification emails if a work item is edited of which the user is assignee or owner
`validation.email-address`	`^[_A-Za-z0-9-\\+]+(\\.[_A-Za-z0-9-]\+)@[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)(\\.[A-Za-z]{2,})$`	the pattern used to validate the email addresses that a user enters in the user profile

4.9. Graphical modeler properties

The following properties can be used to configure the graphical modeler:

Table 13. Graphical modeler properties
Property	Default value	Description
`modeler.addons-palette-location`	`classpath:com/edorasware/addons/palette`	The location for additional addon palette configurations
`modeler.custom-palette-location`	`classpath:com/edorasware/config/custom/palette`	The location for additional project palette configurations

4.10. Encoding properties in property files

Sometime sensitive values need to be configured (such as user names or passwords) and storing these in plain text in the property files is a potential security risk. You can encode property values in a production property file so that the plain text value is not readable. Encoded values will be decoded when the property is loaded, so the original plaintext value is used for configuration.

As an example, we start with a plain text property:

sensitive.value=password:topSecret

We mark any sections of the property that should be encoded using the <ENCODE> delimiters. A property value may contain any combination of delimited encoded values and plain text:

sensitive.value=password:<ENCODE>topSecret<ENCODE>

This property definition (or the complete property file) is then passed through the command-line encoding tool (see below), resulting in an encoded equivalent marked with the <ENC> delimiters:

sensitive.value=password:<ENC>1TOKpX5hMQCd5mcSduoRxCofjybs6xgIEi4yo/zsW+E=<ENC>

This encoded value can then be used in the production property file. Encoded values in a property file will be decoded by edoras one when the property files are loaded, so the original property value can be used in the Spring configuration without exposing the plain text in the property file. A different encoding will also be used each time a value is encoded, so it is also not possible to identify encoded passwords using a known encoded value.

4.10.1. Running the command-line encoding tool

To run the command-line encoding tool you need to unpack the WAR file used to deploy the edoras one application. Next browse to the WEB-INF/lib folder of the extracted WAR file and run the command-line tool as follows:

java -cp edoras-one-server-core-2.0.4.jar:* com.edorasware.one.util.CommandLineParser -encode <value>

The value may either be a plain string to be encoded (e.g. the sensitive.value property value above) or the name of a complete property file. In both cases, the encoded text will be written to the standard output and can be either copied directly from the terminal window or redirected to a new file:

$ java -jar edoras-one-server-core-2.0.4.jar \
    -encode '<ENCODE>topSecret<ENCODE>'
<ENC>bnMeD/y2jbVzzw1OpLkTTo2qsO8obc4vwxmPzZJR3ao=<ENC>
$ java -jar edoras-one-server-core-2.0.4.jar \
    -encode /tmp/input.properties > /tmp/encoded.properties
$

Use " instead of ' on Windows

5. Tomcat configuration

5.1. Connector configuration

To allow to send UTF-8 characters in URIs (e.g. the search requests) we need to allow UTF-8 URI encoding in tomcat (server.xml).

    <!--
        Define a non-SSL HTTP/1.1 Connector on port 8080
        URIEncoding is set to UTF-8
    -->
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
      URIEncoding="UTF-8"
      />

    <!--
        Define an AJP 1.3 Connector on port 8009
        URIEncoding is set to UTF-8
    -->
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" URIEncoding="UTF-8"/>

6. Clustering

To deploy edoras one on two or more nodes you will need the following prerequisites:

Apache HTTPD Server with mod_jk/mod_proxy or any other load balancing component (Apache HTTP Server, mod_jk, mod_proxy)
Two or more Apache Tomcat instances (or any other application server)
File content synchronization (like Gluster)
Redis 2.8 and greater (Redis)

mod_jk is only needed if you use an Apache Tomcat application server. If you use another application server, you will need mod_proxy.

As a load balancer we use the Apache HTTPD Server which sends the request to the Apache Tomcat nodes as configured in the mod_jk configuration. The file content (like documents in edoras one) are stored on the file system which is synchronized beteween the nodes with the help of Gluster. The last part is the Redis server which acts as central point for the distributed caches and the user sessions.

The following diagram shows this setup graphically:

This guide will just show you how to configure edoras one to use Redis as distributed cache and as a distributed session store. Please refer to the following guides on how to install, configure these tools:

6.1. Configuration of edoras one

The properties needed to enable and configure the edoras one clustering support are described in the section Clustering properties.

The following list shows the configuration options needed to run edoras one in a clustered environment:

Enable clustering support by setting the cluster.enable property to true and configure the Redis connection properties
Use the shared file system to store cached converted document content. Because converted document content cache is shared between the nodes, each node has to point to the shared directory where converted content is stored. Each node has to point to the same shared directory for the all nodes. When you start the node in the cluster, evict the cache to keep nodes synchronized.
if you are using file-based content storage, please follow the instructions below to make sure that this is supported by your installation

When you have completed these steps edoras one is configured to run in a clustered environment.

6.1.1. File-based content storage

If you use file-based content management in a clustered environment, you first need to check if the shared file system supports the locking mechanisms needed to ensure data consistency. We provide a command-line lock check tool which creates a test file in the same folder and then tries to lock the file, write a line to the file and unlock it again. This will be executed as many times as specified in the given iterations parameter. Later in this section we also provide a bash script which executes this process several times to simulate concurrent access to this lock file which then tests the real use case.

To run the command-line encoding tool you need to:

unpack the WAR file used to deploy the edoras one application
browse to the WEB-INF/lib folder of the extracted WAR file and run the command-line tool as follows:

java -cp edoras-one-server-core-2.0.4.jar:* com.edorasware.one.util.CommandLineParser -lockcheck <iterations>

You need to run the lock check test tool, and extract the WAR file, on the shared file system you set up before (see first point in the clustered configuration) as there are network file systems which do not properly support the locking. If there is any error while executing the lock check please contact our edorasware support.

The <iterations> parameter is used to set the number of iterations as described above. This check simulates accessing the file with a single instance. You need to use the following bash script to simulate access of multiple processes on the same file which then checks if the file is properly locked and that there are no data inconsistencies. Please create a new file called lock-check.sh inside the WEB-INF/lib folder of the extracted WAR file on the shared file system with the following content:

#!/bin/bash

echo Starting $1 lock check processes ...
pids=""
result=0

# start the lock check java processes
for i in $(seq 1 $1);
do
    java -cp edoras-one-server-core-2.0.4.jar:* com.edorasware.one.util.CommandLineParser -lockcheck $2 &
    pids="$pids $!"
done

# wait for all the processes to finish
for pid in $pids; do
    wait $pid || let "result=1"
done

if [ "$result" == "1" ];
    then
       echo A lock check process failed.
       exit 1
fi

echo All lock check processes completed successfully!

Next make the file executable and then execute it with the following parameters:

./lock-check.sh 10 1000

This will then spawn 10 Java processes with the lock check tool running with 1000 iterations. When everything completes, a success message is shown and this ensures that file-based content storage can be used inside the cluster.