{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>
<emphasis role="bold"><link linkend="ADM.Installation.System_requirements">System requirements</link></emphasis>
</para>
<para>Specifications which are required for running eXo Platform 3.5.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Installation.Install_Tomcat_Bundle">Install the Tomcat bundle</link></emphasis>
</para>
<para>Instructions on how to start up/shut down the server, or to customize variables in Tomcat.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Installation.Install_JBoss_EARS">Install JBoss EARs</link></emphasis>
</para>
<para>Steps to install eXo Platform on JBoss.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold"><link linkend="ADM.Installation.eXo_profiles">Profiles of eXo Platform</link></emphasis>
</para>
<para>The runtime profiles which are used to enable/disable modules of eXo Platform.</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: Multi\-core recommended, 2GHz Minimum
* Memory: 4GB physical RAM, at least 1GB free for JVM's max heap memory (see the JVM settings detailed in the [Install the Tomcat bundle|#ADM.Installation.Install_Tomcat_Bundle] section)
* Disk: 1GB
* Java 6 (Set the JAVA\_HOME environment variable)
* Browser Compatibility:
** Mozilla Firefox 3.6+
** Internet Explorer 7.0+
** Safari 5.0+
** Google Chrome 5.0+

{note}
* The eXo server will run on the 8080 portal, so make sure this port is not currently in use.
* {anchor:id="Crash_ports"}[CRaSH|#ADM.Installation.CRaSH] opens two ports to establish connections by using TELNET or SSH protocols.
To prevent having security threats, it is highly recommended that:
** You change the default SSH and TELNET ports in _crash.war/WEB-INF/crash/crash.properties_.
** You restrict connection to CRaSH ports on your firewall.
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Install the Tomcat bundle|#ADM.Installation.Install_Tomcat_Bundle]
* [Install JBoss EARs|#ADM.Installation.Install_JBoss_EARS]
* [Profiles of eXo Platform|#ADM.Installation.eXo_profiles]

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:   

{code}$PLATFORM_TOMCAT_HOME/start_eXo.sh{code}

* On Windows:       

{code}%PLATFORM_TOMCAT_HOME%\\start_eXo.bat{code}

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

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


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

* On Linux and OS X: 

{code}$PLATFORM_TOMCAT_HOME/stop_eXo.sh{code}

* On Windows:        

{code}%PLATFORM_TOMCAT_HOME%\\stop_eXo.bat{code}

If you receive the message when you try to stop Tomcat as below, you must stop Tomcat by pressing *CtrlC* 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.

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

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

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

{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: _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:

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

*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}} |The name of the configuration directory relatively from "catalina.home", for example, _gatein/conf_.|
| {{-Dexo.profiles}} | List of comma-separated profiles of eXo Platform to activate. |


In the developer mode, the _start\_eXo_ scripts launch eXo Platform in the developer mode with a few JVM options.

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

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

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

{code}$PLATFORM_TOMCAT_HOME/bin/setenv.sh{code}

* Windows: 

{code}$PLATFORM_TOMCAT_HOME\\bin\\setenv.bat{code}

The following is the content of this file:

{code}# Sets some variables
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.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

##### For XML Parser ####
# Define the preferred XML Parser
# If you run eXo Platform on IBM Java, you must use the first one
#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"
EXO_XML="-Djavax.xml.stream.XMLOutputFactory=com.sun.xml.internal.stream.XMLOutputFactoryImpl -Djavax.xml.stream.XMLInputFactory=com.sun.xml.internal.stream.XMLInputFactoryImpl -Djavax.xml.stream.XMLEventFactory=com.sun.xml.internal.stream.events.XMLEventsFactoryImpl"
#########################

CATALINA_OPTS="-Xms256m -Xmx1024m -XX:MaxPermSize=256m $CATALINA_OPTS $LOG_OPTS $SECURITY_OPTS $EXO_OPTS $IDE_OPTS $EXO_PROFILES $EXO_XML"
export CATALINA_OPTS{code}

In the normal mode, the _setenv_ scripts launch eXo Platform with the following JVM options:
{code}-Xms256m
-Xmx1024m
-XX:MaxPermSize=256m
-Djava.security.auth.login.config=../conf/jaas.conf
-Dexo.conf.dir.name=gatein/conf
-Dexo.profiles=default
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
-Djavasrc=$JAVA_HOME/src.zip
-Djre.lib=$JAVA_HOME/jre/lib{code}

*Details*:
|{{-Xms}}|Initial Heap Size (the default is 256 MB).|
|{{-Xmx}}|Maximal Heap Size (the default is 1 GB).|
|{{-Djava.security.auth.login.config}}|The path to the JAAS security file where the security domains and JAAS authentication modules are declared.|
|{{-Dexo.conf.dir.name}}|The path where eXo Platform will start looking at _configuration.properties_ and _configuration.xml_.|
|{{-Dexo.profiles}}|List of comma-separated profiles of eXo Platform to activate.|
|{{-Dorg.apache.commons.logging.Log}}|A simple logging interface abstracting logging APIs.|
|{{-Djavasrc}}| The path to the JAVA source code.|
|{{-Djre.lib}}|The path to the JRE library.|

*About EXO\_XML*: it defines the preferred XML Parser.
* If you run eXo Platform on *IBM Java*, you must use the following:
{code}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"{code}

* Otherwise, you can use the following:
{code}EXO_XML="-Djavax.xml.stream.XMLOutputFactory=com.sun.xml.internal.stream.XMLOutputFactoryImpl -Djavax.xml.stream.XMLInputFactory=com.sun.xml.internal.stream.XMLInputFactoryImpl -Djavax.xml.stream.XMLEventFactory=com.sun.xml.internal.stream.events.XMLEventsFactoryImpl"{code}

{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}} has limited the opened files.
By default, the number of opened files is limited to "1024". You should execute the command: "ulimit \-n 8196" as root before starting the server to avoid this issue.
{note}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [System requirements|#ADM.Installation.System_requirements]
* [Install JBoss EARs|#ADM.Installation.Install_JBoss_EARS]
* [Profiles of eXo Platform|#ADM.Installation.eXo_profiles]

h1. Install JBoss EARs {anchor:id=ADM.Installation.Install_JBoss_EARS}

eXo distribution for JBoss (eXo-Platform-jboss-3.5.x.zip) allows you to deploy eXo Platform on your existing JBoss EAP server located in a folder named _JBOSS\_HOME_.

{docbook}
<citetitle>
<para>
<emphasis role="bold">Install eXo Platform on JBoss</emphasis>
</para>
</citetitle>
{docbook}
*1.* Extract the content of the distribution to a local folder named _eXo-Platform-jboss-3.5.x_.

*2.* Copy the following folder and files from _eXo-Platform-jboss-3.5.x/ears/server/default/deploy_ to _$PLATFORM\_JBOSS\_HOME/server/default/deploy_:

Folders
- gatein.ear
- crash.war

Files
- exo-acme-website-$version.ear
- exo-collaboration-extension-$version.ear
- exo-default-portal-$version.ear
- exo-gadget-pack-$version.ear
- exo-knowledge-extension-$version.ear
- exo-platform-extension-$version.ear
- exo-social-extension-$version.ear
- exo-social-intranet-$version.ear
- exo-wcm-extension-$version.ear
- exo-webos-extension-$version.ear
- exo-workflow-extension-$version.ear
- gatein-ds.xml
- gatein-wsrp-extension-$version.ear
- starter-gatein-$version.ear

*3.* Copy 2 files named _context.xml_ and _server.xml_ from _eXo-Platform-jboss-3.5.x/ears/server/default/deploy/jbossweb.sar_ to _$PLATFORM\_JBOSS\_HOME/server/default/deploy/jbossweb.sar_.

*4.* Copy the following files and folders from _eXo-Platform-jboss-3.5.x/ears/server/default/conf/gatein_ to the folder _$PLATFORM\_JBOSS\_HOME/server/default/conf/gatein_. You may need to create _gatein_ folder if it does not exist.

- cache
- idm
- jcr
- jgroups
- portal
- configuration.properties
- configuration.xml
- controller.xml
- portlet.xml

*5.* Copy the _oauthkey.pem_ file from _eXo-Platform-jboss-3.5.x/ears/server/default/data/gadgets_ to _$PLATFORM\_JBOSS\_HOME/server/default/data/gadgets_. You may need to create folders if they do not exist.

*6.* Configure the JVM parameters.

* On *Linux*, add these lines to the end of _$PLATFORM\_JBOSS\_HOME/bin/run.conf:

{code}# Platform environment variables
EXO_PROFILES="-Dexo.profiles=default"
EXO_OPTS="-Dexo.product.developing=false -Dexo.conf.dir.name=gatein -Dgatein.data.dir=../gatein"
IDE_OPTS="-Djavasrc=$JAVA_HOME/src.zip -Djre.lib=$JAVA_HOME/jre/lib"
# Declare this variable in JAVA_OPTS to run in debug mode
REMOTE_DEBUG="-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n -Dcom.sun.management.jmxremote
-Dorg.exoplatform.container.configuration.debug"
# Here you can define your preferred xml parser - choose one or the other, or none
# If you run eXo Platform under IBM java, you must use the first one
#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"
EXO_XML="-Djavax.xml.stream.XMLOutputFactory=com.sun.xml.internal.stream.XMLOutputFactoryImpl -Djavax.xml.stream.XMLInputFactory=com.sun.xml.internal.stream.XMLInputFactoryImpl -Djavax.xml.stream.XMLEventFactory=com.sun.xml.internal.stream.events.XMLEventsFactoryImpl"
JAVA_OPTS="$JAVA_OPTS $EXO_OPTS $IDE_OPTS $EXO_PROFILES $EXO_XML"{code}

* On *Windows*, add these lines to the end of _$PLATFORM\_JBOSS\_HOME/bin/run.conf.bat_:

{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 "IDE_OPTS=-Djavasrc=$JAVA_HOME/src.zip -Djre.lib=$JAVA_HOME/jre/lib"
set "REMOTE_DEBUG=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n -Dcom.sun.management.jmxremote
-Dorg.exoplatform.container.configuration.debug"
rem # Here you can define your preferred xml parser - choose one or the other, or none
rem # If you run eXo Platform under IBM java, you must use the first one
rem # 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 EXO_XML=-Djavax.xml.stream.XMLOutputFactory=com.sun.xml.internal.stream.XMLOutputFactoryImpl -Djavax.xml.stream.XMLInputFactory=com.sun.xml.internal.stream.XMLInputFactoryImpl -Djavax.xml.stream.XMLEventFactory=com.sun.xml.internal.stream.events.XMLEventsFactoryImpl
set "JAVA_OPTS=%JAVA_OPTS% %EXO_OPTS% %IDE_OPTS% %EXO_PROFILES% %EXO_XML%"{code}

{note:title=Customize enviroment parameters}
* If you prefer using another implementation of SAX, change the class names in _EXO\_XML_ variable.
* You can activate the debug mode of eXo Platfrom by adding _$REMOTE\_DEBUG_ to the _JAVA\_OPTS_ variable.
{note}

*7.* Add the eXo Platform logging categories to _$PLATFORM\_JBOSS\_HOME/server/default/conf/jboss-log4j.xml_.

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

*8.* Configure the _emptySessionPath_ attribute.

From JBoss AS 4 or lower, 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 _$PLATFORM\_JBOSS\_HOME/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}

However, from JBoss AS 5 or higher, _emptySessionPath="true"_ no longer sets the cookie path / by default. Instead, the cookie path
is set via the following element in the _Context_ element in the _server/default/deploy/jbossweb.sar/context.xml_ file.
{code}<SessionCookie path="/" />{code}
Session cookies are now scoped to the context by default.

*9.* Start up the server.

* On Linux and OS X:  

{code}$PLATFORM_JBOSS_HOME/bin/run.sh{code}

* On Windows:          

{code}%PLATFORM_JBOSS_HOME%\\bin\\run.bat{code}

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

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

*10.* Shut down the server.

* On Linux and OS X:

{code}$PLATFORM_JBOSS_HOME/bin/shutdown.sh{code}

* On Windows: 

{code}%PLATFORM_JBOSS_HOME%\\bin\\shutdown.bat{code}

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

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

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [System requirements|#ADM.Installation.System_requirements]
* [Install the Tomcat bundle|#ADM.Installation.Install_Tomcat_Bundle]
* [Profiles of eXo Platform|#ADM.Installation.eXo_profiles]

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.

{warning}
Before modifying and developing eXo Platform, you should choose carefully the profiles that are suitable to your requirements. 
In particular, after you have done any modifications/developments on the server that you started up with your selected profiles, and then switched to another new profiles, you will not see such modifications/developments on eXo Platform.
{warning}

* 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}} | Contain GateIn  Content. |
| {{default}} | Contain all modules except workflow and webos (GateIn, eXo IDE, Collaboration, Social, Knowledge).|
| {{all}} | All available modules. |

For example:

* Start default modules  workflow:

{code}./start_eXo.sh default,workflow{code}

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

{code}./start_eXo.sh collaboration,knowledge{code}

* Start with Social, GateIn and Content.

{code}./start_eXo.sh minimal,social{code}

*For the developer mode*

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

{code}./start_eXo.sh -debug [profiles]{code}

* Start eXo Platform with your selected profiles in Windows:

{code}.\\start_eXo.bat -debug [profiles]{code}

h1. Common Reusable SHell (CRaSH) {anchor:id=ADM.Installation.CRaSH}
[CRaSH|http://www.crashub.org] is deployed in the Java runtime and provides interactions with the JVM. Commands are written
in Groovy and can be developed at runtime, making the extension of the shell with fast development cycle very easy.
It can be run as a standalone application to control its own JVM or as an embedded service in an existing
runtime like a web application.

In eXo Platform, CRaSH is deployed in a web container by using a standard web archive called _crash.war_. This _.war_ file
is used for its packaging capabilities and triggering the CRaSH life cycle, such as starting/stopping CRaSH.
It is a useful tool that connects to the eXo Platform server to provide many features and services such as a set of
JCR commands, and a Groovy Scripts launcher.

This tool is installed by default in Platform 3.5 (for both Tomcat and Jboss bundles). Please refer to [the notice about
ports|#Crash_ports]. In case your environment does not allow CRaSH usage, it can be removed from eXo
Platform bundle (see the [Remove CRaSH|#ADM.Deployment.Remove_crash] section for more details).

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [System requirements|#ADM.Installation.System_requirements]
* [Install the Tomcat bundle|#ADM.Installation.Install_Tomcat_Bundle]
* [Install JBoss EARs|#ADM.Installation.Install_JBoss_EARS]
