eXo Platform 3.5

## Chapter 2. Installation and Startup

eXo Platform is packaged as a deployable enterprise archive defined by the Java EE specification, and as a configuration directory. In this chapter, you will see the following topics:

- System requirements

- Install the Tomcat bundle

- Install JBoss EARs

- Profiles of eXo Platform

## System requirements

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

- CPU: 2GHz

- Memory: 2GB of RAM

- Disk: 200MB

- OS: Windows, Linux or Mac OS X

- Java 6 (Set the JAVAHOME environment variable)

- Browser: Firefox 3.5, 3.6 and 4 or Internet Explorer 7, 8 and 9

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

## Install the Tomcat bundle

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.

Start up the server

eXo Platform leverages the application server on which it is deployed. This means that you only need to start and stop your application with the default commands.

- On Linux and OS X:

    $TOMCAT_HOME/start_eXo.sh

- On Windows:

    %TOMCAT_HOME%\start_eXo.bat

The server is started successfully when you see the following message in your log/console:

    INFO: Server startup in 353590 ms

Shut down the server

- On Linux and OS X:

    $TOMCAT_HOME/stop_eXo.sh

- On Windows:

    %TOMCAT_HOME%\stop_eXo.bat

If you receive the message when you try to stop Tomcat as below, you must stop Tomcat by pressing Ctrl+C or by killing with the -9 command. To perform the kill action automatically, you can run stop_eXo.sh -force that is only available on Linux and OS X systems.

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

The server has been stopped successfully when you see the following message in your log/console:

    INFO: Stopping Coyote HTTP/1.1 on http-8080

Start up eXo Platform by running built-in startup scripts

You can start up eXo Platform by running one of the following built-in startup scripts:

- Linux & OS X: start_eXo.sh

- Windows: start_eXo.bat

- Linux and OS X in the developer mode: start_eXo.sh with the -debug option.

- Windows in the developer mode: start_eXo.bat with the -debug option.

In the normal mode, the start_eXo scripts launch eXo Platform 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

Details:

`-Xms` | Minimal Heap Size (defaults to 256 MB).
`-Xmx` | Maximal Heap Size (defaults to 1 GB).
`-Djava.security.auth.login.config` | Path to the JAAS security file where the security domains and JAAS authentication modules are declared.
`-Dexo.conf.dir.name` | Path where eXo Platform will start looking at configuration.properties and configuration.xml.
`-Dexo.profiles` | List of comma-separated profiles of eXo Plaform to activate.

In the developer mode, the start_eXo scripts launch eXo Platform in the developer mode with a few JVM 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

Details:

`-Dcom.sun.management.jmxremote` | Activate the remote JMX monitoring.
`-Xdebug` -`Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n` | Enable the remote debugging.
`-Dorg.exoplatform.container.configuration.debug` | The container will log in to the console which the .xml file loads.
`-Dexo.product.developing=true` | Deactivate JavaScript and CSS merging for debugging more easily. Next, activate a special language called Magic Locale "ma" showing the property keys instead of the translations.

Now, you can start and run the eXo Platform demo, but you will need to adjust these values for a production setup.

Customize environment variables in Tomcat

Previously, users got used to changing the gatein.sh file, but this file is no longer used since Platform 3.5.0-CR1. Now, to customize the environment variables and JVM memory parameters, you have to modify the setenv.sh file (setenv.bat file in Windows).

This file is located in:

- Linux & OS X:

    $TOMCAT_HOME/bin/setenv.sh

- Windows:

    $TOMCAT_HOME\bin\setenv.bat

The following is the content of this file:

    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

### Note

In Linux environments, the ulimit limits the system-wide resource used. When running eXo Platform, you may get the error message about "Too many open files" because the ulimit had limited the opened files. By default, the number of open files is limited to "1024". You should execute the command "ulimit -n 8196" as root before starting the server to avoid this issue.

## Install JBoss EARs

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.

Install eXo Platform on JBoss

1. Copy the following files to jboss-root/server/default/deploy.

- gatein-ds.xml

- gatein.ear

- gatein-wsrp-extension-$version.ear

- starter-gatein-$version.ear

- exo-wcm-extension-$version.ear

- exo-workflow-extension-$version.ear

- exo-collaboration-extension-$version.ear

- exo-knowledge-extension-$version.ear

- exo-social-extension-$version.ear

- exo-platform-extension-$version.ear

- exo-social-intranet-$version.ear

- exo-acme-website-$version.ear

- exo-default-portal-$version.ear

- exo-gadget-pack-$version.ear

2. Create the jboss-root/server/default/conf/gatein folder, then copy these files to this folder.

- configuration.properties

- configuration.xml

3. Copy the oauthkey.pem file to jboss-root/server/default/conf/gatein/gadgets.

4. Configure the JVM parameters.

- On Linux, add these lines to the end of jboss-root/bin/run.conf:

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

- On Windows, add these lines to the end of jboss-root/bin/run.conf.bat:

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

Adapt to your needs:

- To use another implementation of SAX, change the class names in the EXO_XML variable. For example: com.sun.xml.internal.stream.XMLOutputFactoryImpl.

- To debug the application, simply add $REMOTE_DEBUG to the JAVA_OPTS variable.

5. Add the eXo Platform logging categories to jboss-root/server/default/conf/jboss-log4j.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>

6. Configure the emptySessionPath attribute.

To make Wiki work properly, you have to configure the emptySessionPath attribute in the server.xml file. If you are running Jboss with the "default" profile, this file will be located in server/default/deploy/jbossweb.sar/server.xml/ path.

Depending on the Connector you are using, you have to set the emptySessionPath attribute to "true" for that Connector respectively.

For example, if you are using the AJP Connector, the configuration should be as follows:

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

7. Start up the server.

- On Linux and OS X:

    $JBOSS_HOME/bin/run.sh

- On Windows:

    %JBOSS_HOME%\bin\run.bat

The server is started successfully when you see the following message in your log/console:

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

8. Shut down the server.

- On Linux and OS X:

    $JBOSS_HOME/bin/shutdown.sh

- On Windows:

    %JBOSS_HOME%\bin\shutdown.bat

The server has been stopped successfully when you see the following message in your log/console:

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

## Profiles of eXo Platform

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

- When using Tomcat, you can use a comma-separated list of profiles.

- When using JBoss, you just need to edit EXO_PROFILES in the run.conf(.bat) file.

The following profiles are supported:

Profile | Description
--- | ---
`collaboration` | Enable the Collaboration module.
`knowledge` | Enable the Knowledge module.
`social` | Enable the Social module.
`workflow` | Enable the Workflow add-ons within the Content module.
`webos` | Enable the eXo WebOS module.

Additionally, you can use these composite profiles:

Profile | Description
--- | ---
`minimal` | Contains GateIn + Content.
`default` | Contains all modules except workflow and webos (GateIn, eXo IDE, Collaboration, Social, Knowledge).
`all` | All available modules.

For example:

- Start default modules + workflow:

    ./start_eXo.sh default,workflow

- Start eXo Platform with GateIn, Content, Collaboration and Knowledge enabled.

    ./start_eXo.sh collaboration,knowledge

- Start with Social, GateIn and Content.

    ./start_eXo.sh minimal,social

For the developer mode

- Start eXo Platform with your selected profiles in Linux and OS X:

    ./start_eXo.sh -debug [profiles]

- Start eXo Platform with your selected profiles in Windows:

    .\start_eXo.bat -debug [profiles]