eXo Platform 3.0 Administrators Guide

The normal mode starts with the following JVM options :

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

This is enough to start and run a demo, but you will need to adjust these values for a production setup.

The developer mode scripts add a few more options.

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

Let's stop and explain some parts of the eXo internals in order to 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 his name.

The default portal container in eXo Platform is called simply "portal". This is 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.

	Note
	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 done mostly in configuration.properties. In most cases, this should be the only file a system administrator will need to configure.

In the Tomcat bundle, this file is located at /gatein/conf/configuration.properties

This file contains the builtin configuration for the "portal" portal container.

In most cases, you should not need to 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.

	Note
	Details on how to configure a new portal container are out of the scope of this book 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>

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.

Resource management is exposed via the JMX layer. eXo Platform registers a set of MBean entities in an MBeanServer.

At runtime, the MBeans are registered by the eXo Kernel in the MBeanServer, which the application server creates, and the MBeans are directly viewable in the JMX console. However, we do advocate using a better JMX client such as the JVisualVM, available since Java 6.

In order to enable JMX monitoring in Tomcat, you need to pass the following system property to the VM : -Dcom.sun.management.jmxremote

The built-in REST Managment Provider of GateIn makes some of the MBeans operations accessible as REST endpoints. Administrators could handle the system simply with a browser; no complex configuration needs to be performed.

Only members of the platform/administrators group are given permission to work on REST management. The authentication requires login/password of the user's account.

The base URL to access the REST endpoints is http://localhost:8080/rest/managment, with the last one followed by the parameter parsed in the managed resource's @RESTEndpoint annotation, leading slash then targeted operation. Consider the SkinService, which is annotated @RESTEndpoint("skinservice"); the full URL to access JMX 'getSkinList' method through REST request is http://localhost:8080/rest/management/skinservice/getSkinList

Cache is essential for improving the performance of a server infrastructure.

WCM provides a management view for:

Portlet containers do provide a management view that consists mainly of statistic exposure. The JMX name of a portlet container follows this template: exo:application="Application",portlet="Portlet" where Application is the name of web application and Portlet is the portlet name in the web application.

The portal management exposes the portal resources either for management or for obtaining statistics.

4.2.5.4. Token Store

	Caution
	TODO

GateIn uses an internal store for tokens.

exo:portal="portal",service=TokenStore,name="memory-token" exo:portal="portal",service=TokenStore,name="jcr-token" exo:portal="portal",service=TokenStore,name="gadget-token"

The cluster mode is preconfigured to work out of the box. It relies on the JBoss Cache configuration.

# 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

	Note
	TODO : find and indicate the location of these files in jars. Give a link to the JGroups / JBoss Cache relevant doc

For the very first startup of your JCR cluster, you should only start a single node. This node will initialise the internal JCR database and create the system workspace. Once this first node is deinitely started, you can start the other nodes.

	Note
	This contraint is only for the very first start. Once the initialization has been done, you can start odes in any order

Nodes of the cluster will automatically try to join others at startup. Once they discover each other, they will synchronize their state. During the synchronization the node is not ready to serve requests.

	Note
	How does an admin validate that teh cluster works properly ? Is there something noticeable on screen ?

If you intend to migrate your production system from local (non cluster) mode to cluster, follow these steps :

First, you need to configure a new virtual host in Apache HTTPD for the application server. This is the simplest example of a virtual host:

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

You can find more information about Apache HTTP daemon host here

With the glue method, it is necessary to configure Apache HTTP daemon to work as reverse proxy, which will redirect the client's requests to the app server's HTTP connector. For this type of connection, you will need to include the mod_proxy module in the HTTP demon configuratinon file. This can be found in the httpd.conf file, which is usually located here: /etc/httpd/conf/. However, depending on your OS, this path may vary. You will then need to add some directives to your virtual host configuration.

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

	Note
	In the example above: YOURASHOST - host (IP or DNS name) is the location of your application server. If you run HTTP demon on the same host as your app server, you can change this to localhost. ASHTTPPORT - port, is the location where your app server will listen for incoming requests. For tomcat this value, by default, is 8080. You can find the value at tomcat/conf/server.xml

In this example, HTTP daemon will work in reverse proxy mode (ProxyRequests Off) and will redirect all requests to tcp port 8080 on localhost. So, the configuration of a virtual host will look like the following:

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

For more detail about mod_proxy, review this documentation

As described above, the 'glue' method can be implemented in two ways:

With the first method, you only need the HTTP demon and application server, but settings are limited. With the second method, you can obtain much richer settings, but you will need to download and install additional modules for HTTP Daemon that are not included in the default package.

ProxyPass / ajp://localhost:8009/

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

6.3.3.2. Apache Tomcat's AJP connector

1. Download AJP connector module from here

2. Move the downloaded mod_jk.so file into HTTPD's module directory. For example: /etc/httpd/modules (this may be different, depending on the OS)

3. Create the configuration file for module modjk.conf

	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>
  

You can find more details in the Tomcat docs

1. Place the mod_jk.conf file into the directory where other configuration files for Apache HTTP Demon are located. For example, /etc/httpd/conf.d/

2. Create a workers.properties file, which defines AJP workers for HTTP demon.

	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
  

	Note
	In example above you can change WORKERNAME to any value.

1. Place this file in the same directory as the mod_jk.conf file.

2. Update the virtual host configuration:

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