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. Tenant JSON definition

A new tenant in edoras one is created by adding a new tenant definition to the edoras one installation and restarting the server. The location and file naming convention for the tenant definitions is specified by the tenant.data.location property, and is specific to the application environment.

2.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.

2.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

2.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)
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.

2.4. User information

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

Table 3. 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.

3. Integrating edoras one with other systems

3.1. Mail integration

3.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.

4. Standard properties

TODO: describe the standard edoras one environment properties

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)

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:

6.1. Configuration of edoras one

The only things we need to configure is to use Redis as distributed cache and as a distributed session store. To do this you need to enable the cache-redis and session-redis Spring profiles. You can either add these profiles to the spring.profiles.active system property, or add it in the web.xml as spring.profiles.default context parameter.

Next you need to configure the Redis connection. To do this add the following system properties with the appropriate values.

Table 4. Redis connection properties
Property	Description
`redis.hostname`	the hostname where the Redis server is running (defaults to: `localhost`)
`redis.port`	the port where the Redis server is listening to incoming connections (defaults to: `6379`)
`redis.password`	the password of the Redis server (default is empty)

After that edoras one is configured to run in a clustered environment.