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

Folder
- gatein.ear

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}

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