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 7. If you use Java 8 then you will need to add the following system property such that
it starts up without any errors: javax.xml.accessExternalSchema=all
.
2.2. Database
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 tenant.data.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", "mainColor": "#000011", "backgroundColor": "#000022", "highlightColor": "#000033", "logoUrl": "https://www.google.ch/images/srpr/logo11w.png", "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:
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:
Attribute name | Description |
---|---|
domain |
domain name (used to create user email addresses automatically) |
mainColor |
main color property (optional) |
highlightColor |
highlight color property (optional) |
backgroundColor |
background color property (optional) |
logoUrl |
logo url used in page top left corner (optional) |
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.
3.4. User information
A user entry defines an initial user within the account. The following attributes are supported:
Attribute name | Description |
---|---|
displayName |
user’s display name |
firstName |
user’s first name |
lastName |
user’s last name |
login |
user’s login |
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. Integrating edoras one with other systems
4.1. Mail integration
4.1.1. Outgoing mail
To send outgoing mails, edoras one uses a org.springframework.mail.javamail.JavaMailSender instance.
A suitable bean definition is therefore required in the installation-specific Spring configuration. For debugging purposes in a local development environment, a simple logging implementation is provided that simply logs all outgoing mails to the server log (no mail is actually sent):
<!-- during development, just log outgoing emails -->
<bean id="mailSender" class="com.edorasware.cloud.core.mail.LoggingMailSender"/>
For real servers, a full bean configuration will be required:
<bean name="mailSender" class="org.springframework.mail.javamail.JavaMailSenderImpl">
<property name="defaultEncoding" value="UTF-8"/>
<property name="host" value="smtp.gmail.com"/>
<property name="port" value="465"/>
<property name="username" value="${mail.smtp.username}"/>
<property name="password" value="${mail.smtp.password}"/>
<property name="javaMailProperties">
<props>
<prop key="mail.debug">${mail.debug}</prop>
<prop key="mail.transport.protocol">smtp</prop>
<prop key="mail.smtp.auth">true</prop>
<prop key="mail.smtp.socketFactory.port">465</prop>
<prop key="mail.smtp.socketFactory.class">javax.net.ssl.SSLSocketFactory</prop>
<prop key="mail.smtp.socketFactory.fallback">false</prop>
<prop key="mail.smtp.quitwait">false</prop>
</props>
</property>
</bean>
In a typical installation where the bean configuration is stored on the server where it will be used, the property placeholders shown in this example can be directly replaced with the appropriate values.
For details about mail sender configuration please refer to the Spring documentation.
5. 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 on-premise 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. |
5.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.
5.2. Basic configuration properties
Property | Default value | Description |
---|---|---|
|
|
the location of the edoras one configuration folder. This can only be set as a system property. |
|
|
the base URL where the application is running |
5.2.1. The application.endpoint
property
The application.endpoint
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 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.
5.3. Content manager properties
Property | Default value | Description |
---|---|---|
|
|
when set to |
|
|
the location for the on-disk content conversion cache |
5.4. Query export properties
Property | Default value | Description |
---|---|---|
|
|
the format to be used for exported dates (see SimpleDateFormat) |
|
|
the timezone to be used for exported dates (see TimeZone) |
6. Tomcat configuration
6.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"/>
7. 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)
- NOTE
-
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:
7.1. Configuration of edoras one
There are two things needed to configure one for the clustered environment:
-
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’s
content.conversionCacheDir
property 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. -
use Redis as distributed cache and as a distributed session store. To do this you need to enable the
cache-redis
andsession-redis
Spring profiles. You can either add these profiles to thespring.profiles.active
system property, or add it in theweb.xml
asspring.profiles.default
context parameter. Next you need to configure the Redis connection. To do this add the following system properties with the appropriate values. .Redis connection properties
Property | Description |
---|---|
|
the hostname where the Redis server is running (defaults to: |
|
the port where the Redis server is listening to incoming connections (defaults to: |
|
the password of the Redis server (default is empty) |
After that edoras one is configured to run in a clustered environment.
8. Process debugger (experimental)
- NOTE
-
the process debugger is an experimental feature and should not be used in a production environment. Use the debugger at your own risk.
8.1. Enabling the debugger
To allow process debugging in a particular system you should perform the following steps as the tenant administrator:
-
import and deploy the
ProcessDebugger.zip
application (this App can be found in the release bundle) -
create a
Process Debugging Dashboard
case based on the definition with the same name. There must be only one case with this name -
share the
Process Debugging Dashboard
case with a group of users that should be allowed to use the debugger (e.g.edoras one Modeler
) -
enable the Spring profile
debugger
(e.g. using thespring.profiles.active
JVM property in the intellij idea Run→Run…→Edit configuration…→{project run configuration}→VM options) -
restart the server
8.2. Updating the debugger
To update the debugger when migrating an edoras one installation to a newer version, you need to perform the following steps as the tenant administrator:
-
update the process debugger App by import the ProcessDebugger.zip file from the new release
-
deploy the updated App
-
in the process debugger dashboard case model, use the
Migrate
action to update the dashboard case -
without this step the dashboard will continue to use the old debugger