In eXo platform, the configuration is 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 :
configuration.properties : the main system configuration
configuration.xml : contains the default portal container configuration
portal/portal/configuration.xml : the main external customization entry point for the default portal container.
This section will explain some parts of the eXo internals in so that you will understand the roles of these configuration files.
eXo Platform kernel groups runtime components in 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 for the samples is http://localhost:800/*portal*.
The default portal container can be configured directly inside exo.conf.dir.
But 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.
The exact name of the configuration file can be altered. Please refer to the section dedicated to PortalContainerDefinition in the Kernel reference for more details on portal containers and other options to modify the location of the properties.
Services that run inside a portal container are declared via xml configuration files like configuration.xml. Such files exists in jars, wars and below exo.conf.dir.
XML configuration files also serve as the main way to customize the portal via the multiple plugins offered by eXo components.
Additionally, xml files may contain variables that are populated via properties defined in configuration.properties. Hence, the configuration.properties serves as exposing some chosen variables that are necessary to configure eXo Platform in a server environment.
The system configuration is mostly done in configuration.properties. In most cases, this should be the only file that a system administrator will need to configure.
In the Tomcat bundle, this file is located at /gatein/conf/configuration.properties
This file contains the built-in configuration for the "portal" portal container.
In most cases, you should not change this file.
In case your project does not want to use "portal" as the default portal, this file can be used to to import another PortalContainerDefinition into the root container.
Details on how to configure a new portal container are out of the scope of this guide but is extensively covered in the kernel reference guide.
This file is empty by default. This is where further customizations can be placed. Generally, custom configurations are provided by extension wars. But this file is the last loaded by the kernel. It has a higher priority over any other configuration file, including extensions. So it let's you override any internal component configuration.
This may turn very handy for services or configurations that are not exposed in configuration.properties, but you'd like to tune anyway.
For example, you could decide to change the default transaction timeout to 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>
eXo Platform relies on the application server for its database access, so the database must be configured as a datasource at the AS level. That datasource is obtained by accessing the enterprise naming context (ENC) through the Java Naming and Directory Interface (JNDI) service.
If you intend to bring your eXo to production, the embedded hsql database will not be appropriate and you will need to configure your app server to use another one. You will learn how to configure eXo datasources and in your appserver. If you need to change the datasources name, read Changing the datasources names below.
The steps below will show you how to configure eXo to use a MySQL database. You will need to adapt them to your actual production environement.
You need to prepare two database schema and a technical user to access them.
Connect to your database server using ssh :
ssh root@db.example.org
Verify that MySQL is running :
sudo /etc/init.d/mysqld status
Connect to MySQL :
mysql -u root -p
You are prompted for the password
Create 2 databases : one for idm ($dbname-idm) and the other for jcr $dbname-jcr)
To create one :
create database _$dbname_;
Configure a user that has rights it access it remotely (not only from the host server) :
grant all on _$dbname_.* to '_$username_'@'_$IP_' identified by '_$password_';
$IP = AS hostname
$IP = IP with wildcard (eg 192.168.1.% = all IPs on 192.168.1.x network)
$username = username that eXo Platform will connect with (i.e. 'dbnameuser')
Create the second DataBase
Verify that both DataBases were created :
show databases;
Quit the server with
exit
eXo Platform does not require tables to be created before it starts because it is capable of doing it automatically on the first startup. If you prefer to run a DDL script to create the database objects, please contact eXo Support to obtain the script for your database.
Now that the database is ready, you need to configure eXo to be able to connect to it. The steps depend on the application server. We provide instructions for Tomcat and JBoss
Configuring a datasource for eXo under Tomcat involves two steps:
Edit gatein-ds.xml
Add the JDBC driver
Edit $TOMCATHOME/conf/server.xml
To declare the binding of the datasources in the GlobalNaming context:
Change the driver :
org.hsqldb.jdbcDriver
to
com.mysql.jdbc.Driver
Change the username and password to the values set above
Change the url to access your DataBase :
"jdbc:hsqldb:file:../gatein/data/hsql/exo-jcr_portal"
to
"jdbc:mysql://_$host_:3306/_$dbname_"
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="jdbc/exo-idm_portal" password="_$password_" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:mysql://_$host_:3306/_$dbname-idm_" username="_$username_"/>
You need to add the MySQL connector library in Tomcat. Add mysql-connector-java-5.1.x.jar to $TOMCATHOME/lib/
You can get the latest MySQL connector from : http://dev.mysql.com/downloads/connector/j/
Configuring a datasource for eXo under JBoss involves two steps:
Edit server.xml
Add the JDBC driver
Open $JBOSSHOME/server/default/deploy/gatein-ds.xml
To declare the binding of the datasources in the GlobalNaming context:
Change the driver:
org.hsqldb.jdbcDriver
to
com.mysql.jdbc.Driver
Change the username and password to the values set earlier
Change the url to access your DataBase:
<connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}exo${/}hypersonic${/}exo-xxx_portal-localDB</connection-url>to
<connection-url>jdbc:mysql://_$host_:3306/_$dbname_</connection-url>
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>16</min-pool-size>
<max-pool-size>128</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>16</min-pool-size>
<max-pool-size>128</max-pool-size>
<idle-timeout-minutes>0</idle-timeout-minutes>
<prepared-statement-cache-size>32</prepared-statement-cache-size>
</no-tx-datasource>
</datasources>
You need to add the MySQL connector library in JBoss. Add mysql-connector-java-5.1.x.jar to $JBOSSHOME/server/default/lib/
You can get the latest MySQL connector from : http://dev.mysql.com/downloads/connector/j/
By default, eXo Platform defines two datasources:
exo-jcr_portal - for the Java Content Repository (JCR).
exo-idm_portal - for the organizational model.
You may want to give them a different name. To do this, do as follows :
Edit configuration.properties
Change the datasource name in the application server
$TOMCAT_HOME/gatein/conf/configuration.properties
Indicate to eXo the name of the 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
eXo will automatically append the portal container name ("portal" by default) to these values before it performs a JNDI lookup.
Now, you need to change the name under which the datasources are bound in the JNDI tree by the app server. This is application sever dependent.
In Tomcat, the datasources configuration requires to edit two files :
server.xml
starter.xml
Please refer to Tomcat's JNDI Resources How To for more details on JNDI resources binding in Tomcat.
$TOMCAT_HOME/conf/server.xml
Declare the binding of the datasources in the GlobalNaming context:
<!-- eXo JCR Datasource for portal --> <Resource auth="Container" driverClassName="org.hsqldb.jdbcDriver" logAbandoned="true" maxActive="128" maxIdle="32" maxWait="10000" minEvictableIdleTimeMillis="60000" name="exo-jcr_portal" password="" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:hsqldb:file:../gatein/data/hsql/exo-jcr_portal" username="sa"/> <!-- eXo IDM Datasource for portal --> <Resource auth="Container" driverClassName="org.hsqldb.jdbcDriver" logAbandoned="true" maxActive="128" maxIdle="32" maxWait="10000" minEvictableIdleTimeMillis="60000" name="jdbc/exo-idm_portal" password="" removeAbandoned="true" removeAbandonedTimeout="10" type="javax.sql.DataSource" url="jdbc:hsqldb:file:../gatein/data/hsql/exo-idm_portal" username="sa"/>
$TOMCAT_HOME/conf/Catalina/localhost/starter.xml
We declare resource links that make our datasources accessible to the starter webapp which is used when starting eXo.
<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"/>
Some RDBMS, like MySQL, close idle connections after a while (8h by default on MySQL). Thus, a connection from the pool will be invalid and of course any application SQL command will fail, resulting in errors like:
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, a solution is to use DBCP to monitor 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"
testWhileIdle activates idle connections monitoring
timeBetweenEvictionRunsMillis defines the time interval between two checks in milliseconds (5 minutes in the example)
validationQuery provides a simple SQL command to validate the connection to the RDBMS
You can add these parameters in the datasource configuration file of your application server (i.e. conf/server.xml on Tomcat).
For more details about the configuration, or some examples on other RDBMS and applications servers, please refer to:
eXo needs read/write access to several paths in the local filesystem.
gatein.data.dir=../gatein/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 what path. The temporary column indicates if the data is temporary or persistent.
| variable | content | temporary |
|---|---|---|
gatein.data.dir | jta transactional data | yes |
gatein.jcr.data.dir | jcr swap data | yes |
gatein.jcr.storage.data.dir | binary value storage for jcr | no |
gatein.jcr.index.data.dir | lucene index for JCR | no |
Each variable can be defined as an absolute or 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
eXo Platform requires an SMTP server in order to send emails such as notifications or password reminders.
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
| gatein.email.smtp.host | SMTP hostname |
|---|---|
| gatein.email.smtp.port | SMTP port |
| gatein.email.smtp.starttls.enable | true to enable secure (TLS) SMTP. See RFC 3207 |
| gatein.email.smtp.auth | true to enable SMTP authentication |
| gatein.email.smtp.username | username to send for authentication |
| gatein.email.smtp.password | password to send for authentication |
| gatein.email.smtp.socketFactory.port | Specifies the port to connect to when using the specified socket factory |
| gatein.email.smtp.socketFactory.class | his class will be used to create SMTP sockets. |
More details can be found in the JavaMail API documentation.
For KS, you have to add one of the following properties to the configuration file (/gatein/conf/configuration.properties) to make sure that this mail service works with authenticated SMTP systems:
mail.from= gatein.email.smtp.from=
The value must be the exact email-address of the account configured above.
The embedded WebDAV server lets you control the cache-control http header that it transmits to clients by mimetype. 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 list of key=pair values separated by a semicolon, where keys are a list of mimetypes followed by the cache-control value to set.
If you changed the hostname and port for the chat server, then you'll 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 file $CHATSERVER/conf/openfire.xml.
Configuration is based on properties expressed in an XML syntax. For example, to set property prop.name.is.blah=value, 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
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.
| Property | Description | Default value |
|---|---|---|
| env | ||
| serverbaseURL | base url for all URLs below | http://localhost:8080/ |
| restContextName | name of the rest context | rest |
| provider | ||
| authorizedUser.name | username to authenticate against the HTTP REST service | root |
| authorizedUser.password | password matching with provider.authorizeduser.name | password |
| eXoAuthProvider | ||
| authenticationURL | URL to authenticate users | /organization/authenticate/ |
| authenticationMethod | HTTP method used to pass parameters | POST |
| eXoUserProvider | ||
| findUsersURL | URL to find all users | /organization/xml/user/find-all/ |
| findUsersMethod | HTTP method for user/find-all | GET |
| getUsersURL | URL to retrieve a range of users | /organization/xml/user/view-range/ |
| getUsersMethod | HTTP method for user/view-range | GET |
| usersCountURL | URL to count users | /organization/xml/user/count/ |
| usersCountMethod | HTTP method for user/count | GET |
| userInfoURL | URL to get user info | /organization/xml/user/info/ |
| userInfoMethod | HTTP method for user/info | GET |
| eXoGroupProvider | ||
| groupInfoURL | URL to get group info | /organization/xml/group/info/ |
| groupInfoMethod | HTTP method for info | GET |
| getGroupsAllURL | URL to view all groups | /organization/xml/group/view-all/ |
| getGroupsAllMethod | HTTP method for group/view-all | GET |
| getGroupsRangeURL | URL to view a group range | /organization/xml/group/view-from-to/ |
| getGroupsRangeMethod | HTTP method for group/view-from-to | GET |
| getGroupsForUserURL | URL to get groups for a user | /organization/xml/group/groups-for-user/ |
| getGroupsForUserMethod | HTTP method for groups-for-user | GET |
| groupsCountURL | URL to count groups | organization/xml/group/count |
| groupsCountMethod | HTTP method for group/count | GET |
In order to run properly the chat server needs several ports to be opened in the firewall.
| Port | Type | Description |
|---|---|---|
| 5222 (1) | client to server (xmpp) | The standard port for clients is to connect to the server. Connections may or may not be encrypted. You can update the security settings for this port with exo.chat.port property. |
| 9090 && 9091 | Admin Console (http) | The port used for respectively the unsecured and secured Openfire Admin Console access. |
| 3478 & 3479 | STUN service | The port used for the service that ensures connectivity between entities when behind a NAT. |
Logging in eXo Platform is controlled by the Java Logging API.
By default, logging is configured to:
log errors and warnings on the console
log info level statements in /gatein/logs/gatein-YYYY-MM-DD.log
In Tomcat, the logging 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.
A set of properties control the behaviour of the JCR.
# Type of JCR configuration to use. Possible values are :
# local : local JBC configuration
# cluster : cluster JBC configuration
gatein.jcr.config.type=local
# This is the filter used to notify changes in the jcr index
# in cluster mode, use org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter
gatein.jcr.index.changefilterclass=org.exoplatform.services.jcr.impl.core.query.DefaultChangesFilter
# JCR cache configuration
gatein.jcr.cache.config=classpath:/conf/jcr/jbosscache/${gatein.jcr.config.type}/config.xml
# JCR Locks configuration
gatein.jcr.lock.cache.config=classpath:/conf/jcr/jbosscache/${gatein.jcr.config.type}/lock-config.xml
# JCR Index configuration
gatein.jcr.index.cache.config=classpath:/conf/jcr/jbosscache/cluster/indexer-config.xml
gatein.jcr.jgroups.config=classpath:/conf/jcr/jbosscache/cluster/udp-mux.xml
gatein.jcr.config.type | use cluster if you want to use eXo Platform in cluster mode. Otherwise leave local |
gatein.jcr.index.changefilterclass | in cluster mode change it to org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilter |
gatein.jcr.cache.config | JBoss Cache configuration for the JCR locks |
gatein.jcr.index.cache.config | JBoss Cache Configuraiton for the JCR index |
gatein.jcr.jgroups.config | JGroups configuration to use for cluster mode |
Please refer to the JCR reference guide for the details of configuring these files.
In eXo Platform 3, we have defined the user "root" as super admin by default. You could override this configuration, by modifying the system property named exo.super.user defined in configuration.properties.