Administrator Guide

To run eXo Platform 3.5, your system is required to meet the following specifications or higher.

The eXo server will run on the 8080 portal, so make sure this port is not currently in use.

The easiest way to install eXo Platform is to use the Tomcat bundle. This is a ready-made package on top of the Tomcat 6 application server. First, you need to download and extract the package named eXo-Platform-tomcat-3.5.x.zip on your server.

$TOMCAT_HOME/start_eXo.sh

%TOMCAT_HOME%\start_eXo.bat

INFO: Server startup in 353590 ms

$TOMCAT_HOME/stop_eXo.sh

%TOMCAT_HOME%\stop_eXo.bat

Tomcat did not stop in time. The PID file was not removed.

INFO: Stopping Coyote HTTP/1.1 on http-8080

-Xms256m 
-Xmx1024m 
-XX:MaxPermSize=256m 
-Djava.security.auth.login.config=../conf/jaas.conf  
-Dexo.conf.dir.name=gatein/conf 
-Dexo.profiles=default

-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n 
-Dcom.sun.management.jmxremote 
-Dorg.exoplatform.container.configuration.debug 
-Dexo.product.developing=true 

$TOMCAT_HOME/bin/setenv.sh

$TOMCAT_HOME\bin\setenv.bat

LOG_OPTS="-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog"
SECURITY_OPTS="-Djava.security.auth.login.config=../conf/jaas.conf"
EXO_OPTS="-Dexo.product.developing=false -Dexo.conf.dir.name=gatein/conf"
IDE_OPTS="-Djavasrc=$JAVA_HOME/src.zip -Djre.lib=$JAVA_HOME/jre/lib"
if [ "$EXO_PROFILES" = "" -o "$EXO_PROFILES" = "-Dexo.profiles=default" ] ; then 
	EXO_PROFILES="-Dexo.profiles=default"
fi

CATALINA_OPTS="-Xms256m -Xmx1024m -XX:MaxPermSize=256m $CATALINA_OPTS $LOG_OPTS $SECURITY_OPTS $EXO_OPTS $IDE_OPTS $EXO_PROFILES"
export CATALINA_OPTS

eXo Platform provides EARs packages to deploy in your existing JBoss application server. They are distributed in the package named eXo-Platform-jboss-3.5.x.zip.

# Platform environment variables
EXO_PROFILES="-Dexo.profiles=default"
EXO_OPTS="-Dexo.product.developing=false -Dexo.conf.dir.name=gatein -Dgatein.data.dir=../gatein"
REMOTE_DEBUG="-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n -Dcom.sun.management.jmxremote -Dorg.exoplatform.container.configuration.debug"
EXO_XML="-Djavax.xml.stream.XMLOutputFactory=com.sun.xml.stream.ZephyrWriterFactory -Djavax.xml.stream.XMLInputFactory=com.sun.xml.stream.ZephyrParserFactory -Djavax.xml.stream.XMLEventFactory=com.sun.xml.stream.events.ZephyrEventFactory"
JAVA_OPTS="$JAVA_OPTS $EXO_OPTS $EXO_PROFILES $EXO_XML"

rem # Platform environment variables
set "EXO_PROFILES=-Dexo.profiles=default"
set "EXO_OPTS=-Dexo.product.developing=false -Dexo.conf.dir.name=gatein -Dgatein.data.dir=../gatein"
set "REMOTE_DEBUG=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n -Dcom.sun.management.jmxremote -Dorg.exoplatform.container.configuration.debug"
set "EXO_XML=-Djavax.xml.stream.XMLOutputFactory=com.sun.xml.stream.ZephyrWriterFactory -Djavax.xml.stream.XMLInputFactory=com.sun.xml.stream.ZephyrParserFactory -Djavax.xml.stream.XMLEventFactory=com.sun.xml.stream.events.ZephyrEventFactory"
set "JAVA_OPTS=%JAVA_OPTS% %EXO_OPTS% %EXO_PROFILES% %EXO_XML%"

<!-- Limit the JSR170 categories -->

<category name="exo.jcr">

  <priority value="INFO"/>

</category>

<!-- Limit the JSR-168 and JSR-286 categories -->

<category name="org.exoplatform.services">

  <priority value="INFO"/>

</category>

<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector port="8009" address="${jboss.bind.address}" protocol="AJP/1.3"
    emptySessionPath="true" enableLookups="false" redirectPort="8443" />

<SessionCookie path="/" />

$JBOSS_HOME/bin/run.sh

%JBOSS_HOME%\bin\run.bat

INFO [org.jboss.bootstrap.microcontainer.ServerImpl] (main) JBoss (Microcontainer) [5.1.1 (build: ...)] Started in 5m:29s:259ms

$JBOSS_HOME/bin/shutdown.sh

%JBOSS_HOME%\bin\shutdown.bat

INFO  [org.jboss.bootstrap.microcontainer.ServerImpl] (JBoss Shutdown Hook) Shutdown complete

eXo Platform comes with different runtime profiles, enabling you to customize which modules you want to enable/disable in each eXo Platform instance.

The following profiles are supported:

Additionally, you can use these composite profiles:

For example:

./start_eXo.sh default,workflow

./start_eXo.sh collaboration,knowledge

./start_eXo.sh minimal,social

For the developer mode

./start_eXo.sh -debug [profiles]

.\start_eXo.bat -debug [profiles]

In eXo Platform, the configuration is performed in a folder whose location is controlled by a system property named exo.conf.dir. By default, the gatein.sh startup script sets this property as follows:

-Dexo.conf.dir.name=gatein/conf

So the main entry point for the eXo Platform configuration is /gatein/conf/. This directory contains the following files:

This section explains some parts of the eXo Platform internals so that you can understand the roles of these configuration files.

The eXo Platform Kernel collects runtime components in the portal containers. A portal container holds all components to run a portal instance. It serves portal pages under the servlet context for its name.

The default portal container in eXo Platform is simply called "portal". This explains why the default URL of the samples is http://localhost:8080/portal.

The default portal container can be configured directly inside exo.conf.dir.

However, eXo Platform is capable of running several portal instances simultaneously on the same server. Each instance can be configured and customized independently via files located at: /gatein/conf/portal/$PORTAL_NAME, where $PORTAL_NAME is the name of the portal container.

Services that run inside a portal container are declared via the xml configuration files like configuration.xml. Such files exist in jars, wars and below exo.conf.dir.

The .xml configuration files also serve as the main way to customize the portal via the multiple plugins offered by the eXo Platform components.

Additionally, the .xml files may contain variables that are populated via properties defined in configuration.properties. Hence, the configuration.properties file serves as exposing some selected variables that are necessary to configure eXo Platform in a server environment.

The system configuration is mostly done in the configuration.properties file. In most cases, this should be the only file for the system administrator to configure.

This file contains the built-in configuration for the "portal" portal container.

This file is empty by default. This is where further customizations can be placed. Generally, custom configurations are provided by extension wars. However, this file is the last loaded by the kernel. It has a higher priority over any other configuration files, including extensions. So, you can override any internal component configuration.

This may turn handy services or configurations that are not exposed in configuration.properties.

For example, you can change the default WebDAV update policy by adding the following code to this configuration.xml file:

  <component>

    <key>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</key>

    <type>org.exoplatform.services.jcr.webdav.WebDavServiceImpl</type>

    <init-params>

      <value-param>

        <name>auto-mix-lockable</name>

        <value>false</value>

      </value-param>

      <value-param>

        <name>def-folder-node-type</name>

        <value>nt:folder</value>

      </value-param>

      <value-param>

        <name>def-file-node-type</name>

        <value>nt:file</value>

      </value-param>

      <value-param>

        <name>def-file-mimetype</name>

        <value>text/plain</value>

      </value-param>

      <value-param>

        <name>update-policy</name>

        <value>replace</value>

      </value-param>

    </init-params>

  </component>

eXo Platform relies on the application server for its database access, so the database must be configured as a data source at the AS level. The data source is obtained by accessing the Enterprise Naming Context (ENC) through the Java Naming and Directory Interface (JNDI) service.

ssh root@db.example.org

sudo /etc/init.d/mysqld status

mysql -u root -p

create database _$dbname_;

grant all on _$dbname_.* to '_$username_'@'_$IP_' identified by '_$password_';

show databases;

<!-- eXo JCR Datasource for portal -->

<Resource auth="Container" driverClassName="com.mysql.jdbc.Driver" logAbandoned="true" maxActive="20" maxIdle="10" maxWait="10000" minEvictableIdleTimeMillis="60000" name="exo-jcr_portal" password="_$password_" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:mysql://_$host_:3306/_$dbname-jcr_" username="_$username_"/>



<!-- eXo IDM Datasource for portal -->                

<Resource auth="Container" driverClassName="com.mysql.jdbc.Driver" logAbandoned="true" maxActive="20" maxIdle="10" maxWait="10000" minEvictableIdleTimeMillis="60000" name="exo-idm_portal" password="_$password_" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:mysql://_$host_:3306/_$dbname-idm_" username="_$username_"/>   

<datasources>

    <no-tx-datasource>

      <jndi-name>exo-idm_portal</jndi-name>

      <connection-url>jdbc:mysql://_$host_:3306/_$dbname-idm_</connection-url>

      <driver-class>com.mysql.jdbc.Driver</driver-class>

      <user-name>_$username_</user-name>

      <password>_$password_</password>



      <min-pool-size>5</min-pool-size>

      <max-pool-size>20</max-pool-size>

      <idle-timeout-minutes>0</idle-timeout-minutes>

      <prepared-statement-cache-size>32</prepared-statement-cache-size>

   </no-tx-datasource>

<!-- ...  -->

   <no-tx-datasource>

      <jndi-name>exo-jcr_portal</jndi-name>

      <connection-url>jdbc:mysql://_$host_:3306/_$dbname-jcr_</connection-url>

      <driver-class>com.mysql.jdbc.Driver</driver-class>

      <user-name>_$username_</user-name>

      <password>_$password_</password>



      <min-pool-size>5</min-pool-size>

      <max-pool-size>20</max-pool-size>

      <idle-timeout-minutes>0</idle-timeout-minutes>

      <prepared-statement-cache-size>32</prepared-statement-cache-size>

   </no-tx-datasource>

</datasources>

# JNDI name of the datasource that will be used by eXo JCR
gatein.jcr.datasource.name=java:/comp/env/exojcr
...
# JNDI Name of the IDM datasource
gatein.idm.datasource.name=java:/comp/env/exo-idm

<Resource name="exo-jcr_portal" auth="Container" type="javax.sql.DataSource"
          maxActive="128" maxIdle="32" maxWait="10000"
          testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1" 
          username="${db.username}" password="${db.password}" driverClassName="com.mysql.jdbc.Driver"
          url="jdbc:mysql://${db.host}:${db.port}/${db.jcr.name}"/>

org.hibernate.SessionException: Session is closed!
at org.hibernate.impl.AbstractSessionImpl.errorIfClosed(AbstractSessionImpl.java:72)
at org.hibernate.impl.SessionImpl.getTransaction(SessionImpl.java:1342)

testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1"

# indicates if the jcr datasource is using managed transactions. 
# false by default. 
gatein.jcr.datasource.managed=true

eXo Platform requires the read/write access to several paths in the local file system.

# Arjuna configuration
com.arjuna.ats.arjuna.objectstore.objectStoreDir=${gatein.data.dir}/jta
.....

# Directory for common data (in cluster, mount it as a network shared directory between nodes)
# On standalone JBoss app server it is assignet to ${jboss.server.data.dir} by default.
exo.shared.dir=../gatein

# Configuration directory (in cluster, this directory is per node)
# Usual locations of configuration directory:
# for Tomcat app server it is ${catalina.home}/gatein/conf.
# for JBoss app server it is ${jboss.server.home.dir}/conf/gatein.
gatein.conf.dir=${catalina.home}/${exo.conf.dir.name}

# Data directory
gatein.data.dir=${exo.shared.dir}/data

# path for any JCR data 
gatein.jcr.data.dir=${gatein.data.dir}/jcr

# path for file data inserted in JCR
gatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/values

# path for the jcr index
gatein.jcr.index.data.dir=${gatein.jcr.data.dir}/index

The following table explains what goes in which path. The Temporary column indicates if the data are temporary or persistent (V: temporary, X: persistent).

Each variable can be defined as an absolute or a relative path. The default configuration combines them to obtain a compact tree:

/gatein       # gatein.data.dir
  /data
    /hsql
    /jcr      # gatein.jcr.data.dir
      /index  # gatein.jcr.index.data.dir    
      /swap
      /values # gatein.jcr.storage.data.dir    
    /jta      

The following is the configuration of workspaces (default and system) for JCR repository.

# JCR system and default workspaces

gatein.jcr.repository.default=repository

gatein.jcr.workspace.default=collaboration

gatein.jcr.workspace.system=system

JCR transaction default timeout configured for 7 mins (420 sec) by default. If your application runs longer transactions, you might need a bigger timeout.

# JCR Transaction Service
# TransactionService default timeout (in seconds), set it to one hour here:
gatein.jcr.transaction.timeout=3600

eXo Platform requires the SMTP server to send emails, such as notifications or password reminders.

The Email service can use any SMTP account that needs to be configured in /server/default/conf/gatein/configuration.properties (Or $TOMCAT_HOME/ gatein/conf/configuration.properties if you are using Tomcat).

The relevant section looks like:

#EMail
# Domain name: Help for sending links from email notifications. The default domain name is http://localhost:8080.
gatein.email.domain.url=http://localhost:8080
# Email display in "from" field of email notification.
gatein.email.smtp.from=noreply@exoplatform.com
gatein.email.smtp.username=
gatein.email.smtp.password=
gatein.email.smtp.host=smtp.gmail.com
gatein.email.smtp.port=465
gatein.email.smtp.starttls.enable=true
gatein.email.smtp.auth=true
gatein.email.smtp.socketFactory.port=465
gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

Some authenticated SMTP systems, such as GMail, GMX, MS Exchange, require the value for 'sender' or 'from' in the email message that must be identical to the SMTP user and host.

The Forum application uses it in the notification phase as the default sender. If it is not set, the sender will be empty.

To see more details, refer to JavaMail API documentation.

For Knowledge, you have to modify the following properties to the configuration file /gatein/conf/configuration.properties to make sure that this mail service works with the authenticated SMTP systems:

gatein.email.domain.url=http://localhost:8080
gatein.email.smtp.from=noreply@exoplatform.com

eXo Platform 3.5 provides the Watch document function in Sites Explorer that allows you to receive email notifications of changes on your selected documents.

To customize the email notification, simply change the configuration in the configuration.properties file. This file is defined at:

The relevant section looks like:

# Email content for WatchDocumentService

gatein.ecms.watchdocument.sender=support@exoplatform.com

gatein.ecms.watchdocument.subject=Your watching document is changed

gatein.ecms.watchdocument.mimetype=text/html

gatein.ecms.watchdocument.content=<![CDATA[Dear $user_name,<br><br>The document $doc_name ($doc_title) has changed.<br>

<br>Please go to <a href="$doc_url">$doc_title</a> to see this change.<br><br>]]>

Details:

At present, eXo Platform provides 4 parameters below in the gatein.ecms.watchdocument.content property of the email:

The embedded WebDAV server lets you control the cache-control http header that transmits to clients by the MIME type. This is useful for fine-tuning your website.

The configuration property is exo.webdav.cache-control.

exo.webdav.cache-control=text/*:max-age=3600;image/*:max-age=1800;*/*:no-cache;

The property expects a comma-separated list of key=pair values, where keys are a list of MIME types followed by the cache-control value to set.

eXo Platform allows users to view various types of documents directly in the Sites Explorer through the office server. To do so, the office application must be available in your local device first.

Then, JODConverter will use the default values below to start the office server.

You can customize the default values by adding the properties below in the configuration.properties file:

# JODConverter 3.0
wcm.jodconverter.portnumbers=8100,8101,8102,8103,8104
wcm.jodconverter.officehome=/usr/lib/libreoffice
wcm.jodconverter.taskqueuetimeout=30000
wcm.jodconverter.taskexecutiontimeout=120000
wcm.jodconverter.maxtasksperprocess=200
wcm.jodconverter.retrytimeout=120000

The default office home

"/opt/openoffice.org3"
"/opt/libreoffice"
"/usr/lib/openoffice"
"/usr/lib/libreoffice"

"<SYSTEM_PROGRAMFILES>/OpenOffice.org 3"
"<SYSTEM_PROGRAMFILES>/LibreOffice 3"

"/Applications/OpenOffice.org.app/Contents"
"/Applications/LibreOffice.app/Contents"

The login to eXo Platform is controlled by the Java Logging API.

By default, the login is configured to:

In Tomcat, the login is configured via the conf/logging.properties file. Please refer to Tomcat's Logging Documentation for more information on how to adjust this file to your needs.

The set of properties controls the JCR behaviour.

# Type of JCR configuration to use. Possible values are:
# local : local JBC configuration
# cluster : cluster JBC configuration
gatein.jcr.config.type=local

....

# JCR dialect.
# auto : enabled auto detection
gatein.jcr.datasource.dialect=auto

# JCR Session Registry configuration
# Define here the Max Age of the JCR Session in the session registry (in seconds)
gatein.jcr.sessionregistry.sessionmaxage=300

# JCR cache configuration
gatein.jcr.cache.config=file:${gatein.conf.dir}/jcr/jbosscache/${gatein.jcr.config.type}/cache-config.xml
gatein.jcr.cache.expiration.time=15m

# JCR Locks configuration
gatein.jcr.lock.cache.config=file:${gatein.conf.dir}/jcr/jbosscache/${gatein.jcr.config.type}/lock-config.xml

# JCR Index configuration
gatein.jcr.index.cache.config=file:${gatein.conf.dir}/jcr/jbosscache/${gatein.jcr.config.type}/indexer-config.xml

# JGroups configuration
# for eXo Cache and IDM org-service (in cluster cache-config.xml files)
gatein.jgroups.config=${gatein.conf.dir}/jgroups/jgroups-udp.xml
# for JCR
gatein.jcr.jgroups.config=file:${gatein.jgroups.config}

Details:

For more details on configuring these files, please refer to the eXo JCR Reference Guide.

Please refer to the Cache management view section to see the description about the cache configuration.

# Portal Cache Configuration - TemplateService
cache.exo.portal.TemplateService.capacity=3000
cache.exo.portal.TemplateService.liveTime=600

# Portal Cache Configuration - ResourceBundleData
cache.exo.portal.ResourceBundleData.capacity=3000
cache.exo.portal.ResourceBundleData.liveTime=600

# Portal Cache Configuration - MOPSessionManager
cache.exo.portal.MOPSessionManager.Capacity=5000
cache.exo.portal.MOPSessionManager.TimeToLive=60000
cache.exo.portal.MOPSessionManager.ExpirationTimeout=60000

# Social Cache Configuration - IdentityCache
cache.exo.social.IdentityCache.Capacity:300
cache.exo.social.IdentityCache.TimeToLive:-1

# Social Cache Configuration - IdentityIndexCache
cache.exo.social.IdentityIndexCache.Capacity:300
cache.exo.social.IdentityIndexCache.TimeToLive:-1

# Social Cache Configuration - ProfileCache
cache.exo.social.ProfileCache.Capacity:300
cache.exo.social.ProfileCache.TimeToLive:-1

# Social Cache Configuration - IdentitiesCountCache
cache.exo.social.IdentitiesCountCache.Capacity:2000
cache.exo.social.IdentitiesCountCache.TimeToLive:86400

# Social Cache Configuration - IdentitiesCache
cache.exo.social.IdentitiesCache.Capacity:2000
cache.exo.social.IdentitiesCache.TimeToLive:86400

# Social Cache Configuration - RelationshipCache
cache.exo.social.RelationshipCache.Capacity:10000
cache.exo.social.RelationshipCache.TimeToLive:-1

# Social Cache Configuration - RelationshipFromIdentityCache
cache.exo.social.RelationshipFromIdentityCache.Capacity:10000
cache.exo.social.RelationshipFromIdentityCache.TimeToLive:-1

# Social Cache Configuration - RelationshipsCountCache
cache.exo.social.RelationshipsCountCache.Capacity:800
cache.exo.social.RelationshipsCountCache.TimeToLive:-1

# Social Cache Configuration - RelationshipsCache
cache.exo.social.RelationshipsCache.Capacity:800
cache.exo.social.RelationshipsCache.TimeToLive:-1

# Social Cache Configuration - ActivityCache
cache.exo.social.ActivityCache.Capacity:6000
cache.exo.social.ActivityCache.TimeToLive:-1

# Social Cache Configuration - ActivitiesCountCache
cache.exo.social.ActivitiesCountCache.Capacity:4000
cache.exo.social.ActivitiesCountCache.TimeToLive:-1

# Social Cache Configuration - ActivitiesCache
cache.exo.social.ActivitiesCache.Capacity:4000
cache.exo.social.ActivitiesCache.TimeToLive:-1

# Social Cache Configuration - SpaceCache
cache.exo.social.SpaceCache.Capacity:100
cache.exo.social.SpaceCache.TimeToLive:-1

# Social Cache Configuration - SpaceRefCache
cache.exo.social.SpaceRefCache.Capacity:400
cache.exo.social.SpaceRefCache.TimeToLive:-1

# Social Cache Configuration - SpacesCountCache
cache.exo.social.SpacesCountCache.Capacity:2000
cache.exo.social.SpacesCountCache.TimeToLive:86400

# Social Cache Configuration - SpacesCache
cache.exo.social.SpacesCache.Capacity:2000
cache.exo.social.SpacesCache.TimeToLive:86400

# ECMS Cache Configuration - Viewer
cache.exo.ecms.Viewer.PDFViewer.Capacity=300
cache.exo.ecms.Viewer.PDFViewer.TimeToLive=3600

# ECMS Cache Configuration - Drives
cache.exo.ecms.Drives.ManageDrive.Capacity=300
cache.exo.ecms.Drives.ManageDrive.TimeToLive=86400

# ECMS Cache Configuration - Scripts
cache.exo.ecms.Scripts.ScriptService.Capacity=300
cache.exo.ecms.Scripts.ScriptService.TimeToLive=86400

# ECMS Cache Configuration - Templates
cache.exo.ecms.Templates.TemplateService.Capacity=300
cache.exo.ecms.Templates.TemplateService.TimeToLive=86400

# ECMS Cache Configuration - Webcontent
cache.exo.ecms.Webcontent.InitialWebContentPlugin.Capacity=300
cache.exo.ecms.Webcontent.InitialWebContentPlugin.TimeToLive=600

# ECMS Cache Configuration - WCM Composer
cache.exo.ecms.WCMComposer.Capacity=1000
cache.exo.ecms.WCMComposer.TimeToLive=3600

Default OAuth key configuration

In eXo Platform, OAuth gadgets use a OAuth key to authorize with external service providers. There is always a default key defined in the oauthkey.pem file. This key will be used in case the OAuth gadgets do not indicate a key.

It is strongly recommended that you create your own oauthkey.pem file by using the openssl tool and some commands as follows:

openssl req -newkey rsa:1024 -days 365 -nodes -x509 -keyout testkey.pem -out testkey.pem -subj '/CN=mytestkey'
openssl pkcs8 -in testkey.pem -out oauthkey.pem -topk8 -nocrypt -outform PEM

After creating the new oauthkey.pem file, you can use it to replace the default oauthkey.pem file in the gatein/gadgets/ folder.

Managing resources of eXo Platform is critical for IT operators and system administrators to monitor and supervise the production system.

The eXo Platform product is exposed as a manageable set of resources that can be inspected at runtime to monitor and manage servers.

When it comes to Java, the Java Management Extension (also known as JMX) is the de-facto standard to expose managed resources externally.

This chapter explains various resources provided by the eXo Platform server, possible management actions, and how to obtain relevant metrics.

eXo Platform relies on JAAS for propagating the user identity and roles to the different applications deployed on the server.

The JAAS realm is used by all eXo Platform applications and even propagated to the JCR for Access Control.

By default, eXo Platform uses the JAAS realm named "gatein-domain". If your IT operation rules require you to use another JAAS realm, you will need to modify several files so that eXo Platform can work on your JAAS realm.

Since the security configuration is highly dependent of the app server, each application sever is represented separately.

gatein-domain {
  org.gatein.wci.security.WCILoginModule optional;
  org.exoplatform.services.security.jaas.SharedStateLoginModule required;
  org.exoplatform.services.security.j2ee.TomcatLoginModule required; 
};

<jboss-web>

  <security-domain>java:/jaas/gatein-domain</security-domain>

</jboss-web>

<deployment xmlns="urn:jboss:bean-deployer:2.0">

  <application-policy xmlns="urn:jboss:security-beans:1.0" name="gatein-domain">

    <authentication>

      <login-module code="org.exoplatform.web.security.PortalLoginModule" flag="required">

        <module-option name="portalContainerName">portal</module-option>

        <module-option name="realmName">gatein-domain</module-option>

      </login-module>

      <login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required">

        <module-option name="portalContainerName">portal</module-option>

        <module-option name="realmName">gatein-domain</module-option>

      </login-module>

      <login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required">

        <module-option name="portalContainerName">portal</module-option>

        <module-option name="realmName">gatein-domain</module-option>

      </login-module>

    </authentication>

  </application-policy>

</deployment> 

# Realm name
exo.security.domain=gatein-domain

<login-config>

  <auth-method>FORM</auth-method> 

  <realm-name>gatein-domain</realm-name> 

  <form-login-config>

    ...

  </form-login-config>

</login-config>

<login-config>

  <auth-method>BASIC</auth-method> 

  <realm-name>gatein-domain</realm-name>        

</login-config>

By default, eXo Platform runs in the HTTP mode. However, for the security purposes, you can configure it to run in the HTTPS mode. This section explains how to configure HTTPS mode.

1. Generate your key.

If you do not have an X.509 certificate, you can make a simple certificate using the keytool command.

i. Change the variables in the following command to suit your circumstances, then run it a terminal:

keytool -genkey -alias serverkeys -keyalg RSA -keystore server.keystore -storepass 123456 -keypass 123456 -dname "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY"

Your key will be stored in server.keystore.

ii. Import your key into the Sun JDK keystore (this is required to help running gadget features) with the following command:

keytool -importkeystore -srckeystore server.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts

2. Set up the Jboss configuration to use your new key.

i. Comment the following lines in JBOSS_HOME/server/<PROFILE>/deploy/jbossweb.sar/server.xml:

 <Connector URIEncoding="UTF-8" acceptCount="100" address="${jboss.bind.address}" compressableMimeType="text/html,text/xml,text/plain,text/css,text/javascript" compression="on" compressionMinSize="2048" connectionTimeout="20000" disableUploadTimeout="true" emptySessionPath="true" enableLookups="false" maxHttpHeaderSize="8192" maxSpareThreads="75" maxThreads="150" minSpareThreads="25" noCompressionUserAgents=".*MSIE 6.*" port="8080" protocol="HTTP/1.1" redirectPort="8443"/>

ii. Uncomment the following line:

<Connector SSLEnabled="true" address="${jboss.bind.address}" clientAuth="false" keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore" keystorePass="rmi+ssl" port="8443" protocol="HTTP/1.1" scheme="https" secure="true" sslProtocol="TLS"/>

Then, change the values of keystoreFile and keystorePass to values of your key.

3. Restart your server. You can now access the portal via https://<ServerAddress>:8443/portal.

You can start your backup strategy with the concept of a data repository. It is required to store and arrange backup data properly. The backup of one eXo Platform instance produces a set of files which can be located on various storage media (hard disk, tape, optical or solid storages, or even special remote backup services).

The files are organized in catalogs (folders) or used in different media to the concrete Platform implementation. However, it is highly recommended that you apply the Backup rotation scheme to make the backup implementation effective and reliable.

Also, be sure that your available backup solution of Operating System and Database software are always used, allowing you to simplify the backup organization and avoid mistakes and data loss.

In the pre-backup, you need to stop the whole eXo Platform server.

The backup of eXo Platform consists of the following parts:

In the pre-backup, it is recommended that you prepare for tools, such as scripts, to restore data quickly and safely.

To learn more about the basic principles of eXo Platform backup and how to create your backup implementation, see the following Backup Planning example:

It is a general case when the backup is organized in the two-cycle rotation: backup files are stored everyday and older data are stored weekly, and the data storage history will be planned for three years.

To implement this approach, the daily backup is run (at night when the site is not in use) and stores result files (database and JCR files) on the network storage in the following structure:

The backup files are named to the ISO 8601 date format:

For the files backup, eXo Platform provides a shell script running on the eXo Platform server. This script does the following actions:

1. Stop the whole eXo Platform instance by using the shell command: stop_eXo. To see more details, see the Installation and Startup chapter.

2. Run the backup procedure, including:

3. Archive the backup files to your backup storage.

4. Start the eXo Platform server.

Restoring from the backup can be used in several cases, such as failure, or site duplication. Similar to the backup, it is important to stop the whole eXo Platform before restoring. Next, do the main steps to start restoring from the backup of eXo Platform:

1. Unarchive the backup files from the backup storage to the temporary location.

2. Stop the whole eXo Platform instance by using the shell command stop_eXo. To see more details, see the Installation and Startup chapter.

3. Run the restoring procedure to restore from the backup local files for:

4. Start the eXo Platform server.

Steps described above are based on the whole backup of data. However, the incremental backup approach allows you to preserve data by creating multiple copies that are based on the differences in those data. The successive copy of data only contains the portion which has been changed since the preceding copy has been created.

In steps described above, it is also possible to implement an incremental backup against the eXo Platform data.

Users of the Unix platforms can use the rsync tool for files synchronization and implement the incremental backup for JCR value and index files. Meanwhile, Microsoft Windows users can use the Backup utility (Ntbackup.exe).

These tools can be used in conjunction with a database incremental backup feature of your RDBMS to implement the eXo Platform incremental backup solution. However, all backup targets described above should be counted.

In case of the example, it is possible to organize the full backup weekly (on Sunday) and incrementals daily. The incremental backup will be faster, and reduce your site maintenance daily.

Clustering allows eXo Platfrom users to run various portal instances on several parallel servers which are also called nodes. The load is distributed across different servers, so the portal is still accessible via other cluster nodes in case of any failed servers. Thanks to adding more nodes to the cluster, eXo Platform's performance can be much improved. A cluster is a set of nodes which is managed together and participate in the workload management. Installing eXo Platform in the cluster mode is considered in the following main cases:

These characteristics should be handled by the overall architecture of your system. The Load Balancing is typically achieved by a front server or device that distributes the request to the cluster nodes. Also, the High Availability on the data layer can be typically achieved using the native replication implemented by Relation Database Management System (RDBMS) or Shared File Systems, such as SAN and NAS.

eXo Platform comes with two sample portals that show the capabilities of the product. However, once implementing your own extensions, you may not need these sample portals. In some cases, you usually want to remove them before deploying your system in production.

The following instructions are used in cases where the hsqldb embedded database configuration is used.

Extensions are packaged as the Java EE web applications and packaged as the normal .war files. To deploy the custom extension, you may do as for any other web apps.

In Tomcat, this ends up by copying the war archive to the webapps folder.

However, the GateIn extension mechanism imposes that the starter.war webapp starts after all extension wars.

This is the case for the sample applications bundled by default.

There are several ways to control the loading order of webapps in Tomcat. Please refer to Tomcat's Deployer How To.

It may be necessary to use the HTTP server as a front-end for Tomcat. For example, you may want to keep more than one application server on the same host, and/or you want to access these app servers with the separate DNS names, without adding a port to the URL.

There are two methods that allow you to "glue" Apache HTTP Daemon and Tomcat application server:

<VirtualHost *:80>
  ServerName      Enter your server DNS name here
  RedirectMatch permanent "^/?$" "/portal/"
</VirtualHost>

ProxyRequests   Off
ProxyPass	 "/" http://YOUR_AS_HOST:AS_HTTP_PORT/
ProxyPassReverse "/" http://YOUR_AS_HOST:AS_HTTP_PORT/

<VirtualHost *:80>
  ServerName      Enter your server DNS name here
  RedirectMatch	permanent "^/?$" "/portal/"
  ProxyRequests   Off
  ProxyPass	 "/" http://localhost:8080/
  ProxyPassReverse "/" http://localhost:8080/
</VirtualHost>

ProxyPass / ajp://localhost:8009/

<VirtualHost *:80>
  ServerName      Enter your server DNS name here
  RedirectMatch	permanent "^/?$" "/portal/"
  ProxyRequests   Off
  ProxyPass	/ ajp://localhost:8009/
</VirtualHost>

LoadModule    jk_module  modules/mod_jk.so
<IfModule jk_module>
  # ---- Where to find workers.properties
        JkWorkersFile   conf.d/workers.properties
  # ---- Where to put jk logs
  JkLogFile       logs/mod_jk.log
  # ---- Set the jk log level [debug/error/info]
  JkLogLevel    info
  # ---- Select the timestamp log format
  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
  JkRequestLogFormat "%w %R %T"
  # ---- Send everything for context /examples to worker named worker1 (ajp13)
  JkMountFileReload       "0"
</IfModule>

worker.list=status, WORKER_NAME
# Main status worker
worker.stat.type=status
worker.stat.read_only=true
worker.stat.user=admin
# Your AJP worker configuration
worker.WORKER_NAME.type=ajp13
worker.WORKER_NAME.host=localhost
worker.WORKER_NAME.port=8109
worker.WORKER_NAME.socket_timeout=120
worker.WORKER_NAME.socket_keepalive=true

<VirtualHost *:80>
  ServerName      Enter your server DNS name here
  RedirectMatch	permanent "^/?$" "/portal/"
  ProxyRequests   Off
  JkMount         /*	WORKER_NAME
</VirtualHost>

The session timeout defines the validation period of a session. In the portal environment, such as eXo Platform, it is highly recommended that all web applications have the same session timeout value.

The session timeout is configurable individually for each web application in the web.xml file:

<!-- ==================== Default Session Configuration ================= --> 

<!-- You can set the default session timeout (in minutes) for all newly   --> 

<!-- created sessions by modifying the value below.                       --> 

<session-config> 

  <session-timeout>30</session-timeout> 

</session-config>

There are many changes between eXo Platform 3.0 and eXo Platform 3.5, including data type structure (JCR node type), pre-defined data, templates and gadgets:

All of changes above will be migrated automatically by the migration tools that are detailed as below.

Step 1. Prepare an environment.

1. Back up the eXo Platform 3.0 and its data.

2. Configure eXo Platform 3.5 to run with the eXo Platform 3.0 data as follows:

i. With Tomcat bundle, copy 2 folders "index" and "value" from $PLF-3.0-TOMCAT_HOME/gatein/data/jcr to $PLF-3.5-TOMCAT_HOME/gatein/data/jcr. With Jboss bundle, copy 2 folders "index" and "value" from $PLF-3.0-JBOSS_HOME/gatein/jcr to $PLF-3.5-JBOSS_HOME/server/default/data/gatein/jcr.

ii. With Tomcat bundle, configure the database connections in the $PLATFORM-3.5-TOMCAT_HOME/conf/server.xml file to point to the eXo Platform 3.0 database.

For example, if your eXo Platform 3.0 runs on mySQL database, you need to configure the server.xml file as below:

<!-- eXo JCR Datasource for portal -->
	<Resource name="exo-jcr_portal" auth="Container" type="javax.sql.DataSource"
		maxActive="128" maxIdle="32" maxWait="10000"
		testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1"
		username="${db.username}" password="${db.password}" driverClassName="com.mysql.jdbc.Driver"
			url="jdbc:mysql://${db.host}:${db.port}/${db.jcr.name}"/>

<!-- eXo IDM Datasource for portal -->
	<Resource name="exo-idm_portal" auth="Container" type="javax.sql.DataSource"
	   maxActive="128" maxIdle="32" maxWait="10000"
	   testWhileIdle="true" timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1"
	   username="${db.username}" password="${db.password}" driverClassName="com.mysql.jdbc.Driver"
			url="jdbc:mysql://${db.host}:${db.port}/${db.idm.name}"/>

With Jboss bundle, configure the $PLF-3.5-JBOSS_HOME/server/default/deploy/gatein-ds.xml file.

    <!-- eXo IDM for portal -->

    <no-tx-datasource>

      <jndi-name>exo-idm_portal</jndi-name>

      <connection-url>jdbc:mysql://_$host_:3306/_$dbname-idm_</connection-url>

      <driver-class>com.mysql.jdbc.Driver</driver-class>

      <user-name>_$username_</user-name>

      <password>_$password_</password>

      <min-pool-size>5</min-pool-size>

      <max-pool-size>20</max-pool-size>

      <idle-timeout-minutes>0</idle-timeout-minutes>

      <prepared-statement-cache-size>32</prepared-statement-cache-size>

   </no-tx-datasource>

 

   <!-- eXo JCR Datasource for portal -->

   <no-tx-datasource>

      <jndi-name>exo-jcr_portal</jndi-name>

      <connection-url>jdbc:mysql://_$host_:3306/_$dbname-jcr_</connection-url>

      <driver-class>com.mysql.jdbc.Driver</driver-class>

      <user-name>_$username_</user-name>

      <password>_$password_</password>

      <min-pool-size>5</min-pool-size>

      <max-pool-size>20</max-pool-size>

      <idle-timeout-minutes>0</idle-timeout-minutes>

      <prepared-statement-cache-size>32</prepared-statement-cache-size>

   </no-tx-datasource>