{docbook}
<abstract>
<para>
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:
</para>
<itemizedlist>
<listitem>
<para>
<link linkend="ADM.Installation.System_requirements">System requirements</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="ADM.Installation.Install_Tomcat_Bundle">Install the Tomcat bundle</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="ADM.Installation.Install_JBoss_EARS">Install JBoss EARs</link>
</para>
</listitem>
<listitem>
<para>
<link linkend="ADM.Installation.eXo_profiles">Profiles of eXo Platform</link>
</para>
</listitem>
</itemizedlist>
</abstract>
{docbook}

h1. System requirements {anchor:id=ADM.Installation.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 JAVA_HOME 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.

h1. Install the Tomcat bundle {anchor:id=ADM.Installation.Install_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.

{docbook}
<citetitle>
<para><emphasis role="bold">
Start up the server
</emphasis>
</para>
</citetitle>
{docbook}

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:   {screen}$TOMCAT_HOME/start_eXo.sh{screen}

* On Windows:          {screen}%TOMCAT_HOME%\\\\start_eXo.bat{screen}

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

{screen}
INFO: Server startup in 353590 ms
{screen}


{docbook}
<citetitle>
<para><emphasis role="bold">
Shut down the server
</emphasis>
</para>
</citetitle>
{docbook}

* On Linux and OS X: {screen}$TOMCAT_HOME/stop_eXo.sh{screen}

* On Windows:        {screen}%TOMCAT_HOME%\\\\stop_eXo.bat {screen}

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 {noformat}-9{noformat} command. To perform the *kill* action automatically, you can run *{noformat}stop_eXo.sh -force{noformat}* that is only available on Linux and OS X systems.

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

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

{screen}
INFO: Stopping Coyote HTTP/1.1 on http-8080
{screen}



{docbook}
<citetitle>
<para><emphasis role="bold">
Start up eXo Platform by running built-in startup scripts
</emphasis>
</para>
</citetitle>
{docbook}

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

* Linux & OS X: *{noformat}start_eXo.sh{noformat}*.

* Windows: *{noformat}start_eXo.bat{noformat}*.

* Linux and OS X in the developer mode: *{noformat}bin/gatein-dev.sh{noformat}*.

* Windows in the developer mode: *{noformat}bin/gatein-dev.bat{noformat}*.

In the normal mode, the *{noformat}start_eXo{noformat}* scripts launch eXo Platform with the following JVM options:

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

*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 *{noformat}gatein-dev{noformat}* scripts launch eXo Platform in the developer mode with a few JVM options.

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

*Details*:

| {noformat}-Dcom.sun.management.jmxremote{noformat} | Activate the remote JMX monitoring. |
| {noformat}-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n{noformat} | Enable the remote debugging. |
| {noformat}-Dorg.exoplatform.container.configuration.debug{noformat} | The container will log in to the console which the .xml file loads. |
| {noformat}-Dexo.product.developing=true{noformat} | 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.

{docbook}
<citetitle>
<para><emphasis role="bold">
Customize environment variables in tomcat
</emphasis>
</para>
</citetitle>
{docbook}

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, you have to modify the _setenv.sh_ file (_setenv.bat_ file in Windows).

This file is located in:
* Linux & OS X: _{noformat}$TOMCAT_HOME/bin/setenv.sh{noformat}_.
* Windows: _{noformat}$TOMCAT_HOME/bin/setenv.bat{noformat}_.

The following is the content of this file:

{code}
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="$CATALINA_OPTS $LOG_OPTS $SECURITY_OPTS $EXO_OPTS $IDE_OPTS $EXO_PROFILES"
export CATALINA_OPTS
{code}

h1. Install JBoss EARs {anchor:id=ADM.Installation.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_.
{docbook}
<citetitle>
<para>
<emphasis role="bold">To install eXo Platform on JBoss, follow these steps</emphasis>:
</para>
</citetitle>
{docbook}
*1.* Copy the following files to _{noformat}jboss-root/server/default/deploy{noformat}_.

- 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 folder _{noformat}jboss-root/server/default/conf/gatein{noformat}_ and then copy these files to this folder.

- configuration.properties

- configuration.xml

*3.* Copy the file _{noformat}oauthkey.pem{noformat}_ to _{noformat}jboss-root/server/default/conf/gatein/gadgets{noformat}_.

*4.* Configure the JVM parameters.

* On *Linux*, add these lines to the end of _{noformat}jboss-root/bin/run.conf{noformat}:

{code}
# 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"
{code}

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

{code}
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%"
{code}

*Adapt to your needs:*
* To use another implementation of SAX, change the class names in the _{noformat}EXO_XML{noformat}_ variable. For example: _com.sun.xml.internal.stream.XMLOutputFactoryImpl_.
* To debug the application, simply add _{noformat}$REMOTE_DEBUG{noformat}_ to the _{noformat}JAVA_OPTS{noformat}_ variable.

*5.* Add the eXo Platform logging categories to _{noformat}jboss-root/server/default/conf/jboss-log4j.xml{noformat}_.

{code: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>
{code}

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

{code}
<!-- 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" />
{code}

*7.* Start up the server.

* On Linux and OS X:   {screen}$JBOSS_HOME/bin/run.sh{screen}

* On Windows:          {screen}%JBOSS_HOME%\\\\bin\\\\run.bat{screen}

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

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

*8.* Shut down the server.

* On Linux and OS X: {screen}$JBOSS_HOME/bin/shutdown.sh{screen}

* On Windows: {screen}%JBOSS_HOME%\\\\bin\\\\shutdown.bat {screen}

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

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


h1. Profiles of eXo Platform {anchor:id=ADM.Installation.eXo_profiles}


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 _{noformat}EXO_PROFILES{noformat}_ in the _run.conf(.bat)_ file.

The following profiles are supported:

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

Additionally, you can use these composite profiles: 
|| Profile || Description ||
| {{minimal}} | Contains GateIn + eXo Content. |
| {{default}} | Contains all modules except workflow and webos (GateIn, eXo IDE, eXo Collaboration, eXo Social, eXo Knowledge).|
| {{all}} | All available modules. |

For example:

* _{noformat}./start_eXo.sh default,workflow{noformat}_: Start default modules + workflow.

* _{noformat}./start_eXo.sh collaboration,knowledge{noformat}_: Start eXo Platform with GateIn, eXo Content, eXo Collaboration and eXo Knowledge enabled.

* _{noformat}./start_eXo.sh minimal,social{noformat}_: Start with eXo Social, GateIn and eXo Content.
