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:

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

h2. 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:   {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}

h2. Shut down the server.

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


h2. 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: *{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.

h2. 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, 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_.

To install eXo Platform on JBoss, follow these steps:

*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

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

*7.* 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, the *{noformat}start_eXo{noformat}* command accepts a comma-separated list of profiles. When using JBoss, you need to modify the run.conf file (run.conf.bat in Windows), then edit the line containing _{noformat}EXO_PROFILES="-Dexo.profiles=default"{noformat}_.

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.
