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.

configuration.properties 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.

configuration.xml 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 decide to change the default transaction timeout for 2 minutes with this piece of xml:

<component> 

  <key>org.exoplatform.services.transaction.TransactionService</key> 

  <type>org.exoplatform.services.transaction.jbosscache.JBossTransactionsService</type> 

  <init-params> 

    <value-param> 

      <name>timeout</name> 

      <value>120</value> 

    </value-param> 

  </init-params> 

</component>

If you intend to bring your eXo Platform to production, the embedded hsql database will not be appropriate and you will need to configure your app server to use another one. You need to learn how to configure eXo Platform data sources and your app server. If you need to change the data sources name, read Change the datasources names below.

Step 1. Prepare your database server.

You need to prepare two database schema, then do as follows:

1. Connect to your database server using the ssh command:

ssh root@db.example.org

2. Verify that MySQL is running:

sudo /etc/init.d/mysqld status

3. Connect to MySQL:

mysql -u root -p

In this step, you will be prompted for entering your password.

4. Create 2 databases: one for idm ($dbname-idm) and the other for jcr $dbname-jcr). For example:

i. Create the first database:

create database _$dbname_;

ii. Configure the user who have the remote access right (not only from the host server):

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

In which, $IP = AS host name, $IP = IP with wildcard (eg 192.168.1.% = all IPs on 192.168.1.x network) and $username = username that eXo Platform will connect with (i.e. 'dbnameuser').

5. Verify that both databases were created successfully:

show databases;

6. Quit the server with the exit command.

Step 2. Configure eXo Platform.

After the database is ready, you need to configure eXo Platform to connect to it. The configuration steps may be different, depending on the application server. Here, instructions are for Tomcat and JBoss.

Tomcat bundle:

In Tomcat, the data sources configuration requires you to edit two files:

To edit the server.xml file:

1. Open the file following the $TOMCAT_HOME/conf/server.xml path.

2. Declare the binding of the data sources in the GlobalNaming context:

The code now should look like:

<!-- 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_"/>   

3. Add the JDBC driver. In this step, you need to add the MySQL connector to Tomcat by adding mysql-connector-java-5.1.x.jar to $TOMCAT_HOME/lib/.

To edit the starter.xml file:

1. Open the starter.xml file to the $TOMCAT_HOME/conf/Catalina/localhost/starter.xml path.

2. Declare the resource links that make your datasources accessible to the starter webapp which is used when starting eXo Platform.

<ResourceLink global="exo-jcr_portal" name="exo-jcr_portal" type="javax.sql.DataSource"/>



<ResourceLink global="exo-idm_portal" name="exo-idm_portal" type="javax.sql.DataSource"/>

JBoss:

To configure the data source for eXo Platform under JBoss, do as follows:

1. Edit the gatein-ds.xml file.

i. Open the file following the $JBOSS_HOME/server/default/deploy/gatein-ds.xml path.

ii. Declare the binding of the data sources in the GlobalNaming context:

The configuration should now look like:

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

2. Add the JDBC driver. In this step, you need to add the MySQL connector library in JBoss by adding mysql-connector-java-5.1.x.jar to $JBOSS_HOME/server/default/lib/.

3. Rename the data source.

By default, eXo Platform defines two data sources:

You may want to rename the data source as follows:

i. Open and edit the configuration.properties path.

In this step, indicate to eXo name of the data sources.

# 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

ii. Change the data source name in the application server.

In this step, you need to change the name under which the data sources are bound in the JNDI tree by the app server. This is a dependent application sever.

Q1. How to configure eXo Platform to connect to other database systems?

Configuring eXo Platform to connect to other database can be done easily. eXo Platform provides sample configuration files in the folders:

In each folder, you will find two sample xml files: gatein-ds.xml for JBoss and server.xml for Tomcat.

Each file contains 2 preconfigured datasources. For example (JCR datasource in mysql/server.xml):

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

You simply replace the variables with the expected values:

Please remember to add the JDBC connector JAR in the classpath of your application server.

You can download the official JDBC connector JARs from the following websites:

Q2. How to remove the idle MySQL connections?

Some RDBMSs, like MySQL, close the idle connections after a period (8 hours on MySQL by default). Thus, a connection from the pool will be invalid and any application SQL command will fail, resulting in errors as below:

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

To avoid this, you can use DBCP to monitor the idle connections and drop them when they are invalid, with the parameters testWhileIdle, timeBetweenEvictionRunsMillis and validationQuery.

The validation query is specific to your RDBMS. For example, on MySQL, you would use:

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

In which:

You can add these parameters to the data source configuration file of your application server, for example: conf/server.xml on Tomcat.

For more details on the configuration, or some examples on other RDBMS and applications servers, please refer to:

If you change the host name and port for the Chat server, you will need to edit two properties:

# IP or hostname for the eXo Chat XMPP server
exo.chat.server=127.0.0.1

# TCP port for where the eXo Chat server listens for XMPP calls
exo.chat.port=5222

The standalone Chat server is configured in the $CHATSERVER/conf/openfire.xml file.

Configuration is based on properties expressed in the XML syntax. For example, to set the prop.name.is.blah=value property, you would write this xml snippet:

<prop>

  <name>

    <is>

      <blah>value</blah>

    </is>

  </name>

</prop>

Openfire has an extensive list of configuration properties. Please read the list of all properties in Openfire documentation for more details.

The Chat server is an Openfire server bundled with plugins and configurations that allow connectivity to eXo Platform. The following properties are used to configure it.

In eXo Platform, the user "root" is defined as the super-admin by default. You could override this configuration by modifying the system property named exo.super.user defined in configuration.properties.

In eXo Platform, the default users, excluding Super-admin user, are defined in "Acme WebSite" and "Office Intranet" extensions. By deleting those extensions, the users "john", "demo", "james" and "mary" will not be created.

The proxy service allow accessing any site which matches the white-list domains, unless it belongs to the black-list. If the site is not defined in neither the white list nor black list, access will be denied. Multiple values can be added for each list and wildcards can also be used.

The following is an example of the Gadget Proxy configuration:

<component>

  <key>org.exoplatform.web.security.proxy.ProxyFilterService</key>

  <type>org.exoplatform.web.security.proxy.ProxyFilterService</type>

  <init-params>

    <values-param>

      <name>white-list</name>

      <value>*.example.com</value>

      <value>www.example.net</value>

    </values-param>

    <values-param>

      <name>black-list</name>

      <value>evil.example.com</value>

    </values-param>

  </init-params>

</component>