Chapter 8. Deployment

How to remove the sample applications
Remove Acme Website
Remove Acme Social Intranet
Remove the docs webapp
Remove crash
How to deploy a custom extension
How to setup an Apache Frontend
Base configuration for apache
Connection via HTTP protocol (Apache mod_proxy)
Connection via AJP protocol
How to configure the session-timeout for the web server
Server Tomcat
Sever Jboss

eXo Platform comes with two sample portals that showcase the capabilities of the product. Before deploying your system in production, you will want to remove these sample apps.

Caution

The instructions below assume that you are using the hsqldb embedded database configuration.

The Acme site is a sample extension that demonstrates an example of intranet you could implement with eXo platform. Once you have implemented your own extension, you will not likely need the acme website anymore. To remove the Acme site, do as follows:

  1. Stop the server shutdown.sh

  2. Delete acme-portal.war

  3. Delete exo.ecms.ext.acme.config.jar

  4. Delete gatein/data

  5. Restart

The Acme Social Intranet is a sample extension that demonstrates an example of intranet you could implement with eXo platform. Once you have implemented your own extension, you will not likely need the Social Intranet anymore. To remove the Acme Social Instranet, do as follows:

  1. Stop the server shutdown.sh

  2. Delete office-portal.war

  3. Delete exo.platform.office.config.jar

  4. Delete gatein/data

  5. Restart

The docs are bundled as a convenience to be easily browsable while your portal is started. For production deployments, you will likely not need them. The docs webapp consists in a file docs.war located in tomcat/webapps and in jboss/server/default/deploy. In jboss, it is actually a folder named docs.war.

To remove docs, webapp do as follows:

  1. Stop the server shutdown.sh

  2. Delete file of folder docs.war

  3. Restart

Crash is a complementary tool for development and maintenance. As it opens telnet and ssh sockets, we strongly advise to remove crash for your production deployments Crash consists in a file crash.war in tomcat/webapps.

To remove crash, do as follows:

  1. Stop the server shutdown.sh

  2. Delete file crash.war

  3. Restart

Extensions are packaged as java EE web applications and come packaged as normal .war files. Hence, to deploy a custom extension, you will likely do as for any other webapp. In Tomcat this ends up by copying the war archive to the webapps folder

However, note that the Gatein extension mechanism imposes that the starter.war webapp starts after all extension wars. This is the case for the sample applications bundled by defaut, but you must ensure that for your custom applications. There are several ways to control le loading order of webapps in Tomcat. Please refer to Tomcat's Deployer How To

It may be necessary to use an HTTP server as a frontend for tomcat. For example, you may want to keep more then one application server on the same host, and/or you want to access these app servers with separate DNS names, without having to add a port to the URL. There are two methods that allow you to "glue" Apache HTTP Daemon and tomcat application server:

First, you need to configure a new virtual host in Apache HTTPD for the application server. This is the simplest example of a virtual host:

        <VirtualHost *:80>
                ServerName      Enter your server DNS name here
                RedirectMatch permanent "^/?$" "/portal/"
        </VirtualHost>

You can find more information about Apache HTTP daemon host here

With the glue method, it is necessary to configure Apache HTTP daemon to work as reverse proxy, which will redirect the client's requests to the app server's HTTP connector. For this type of connection, you will need to include the mod_proxy module in the HTTP demon configuratinon file. This can be found in the httpd.conf file, which is usually located here: /etc/httpd/conf/. However, depending on your OS, this path may vary. You will then need to add some directives to your virtual host configuration.

ProxyRequests   Off
ProxyPass	 "/" http://YOUR_AS_HOST:AS_HTTP_PORT/
ProxyPassReverse "/" http://YOUR_AS_HOST:AS_HTTP_PORT/

Note

In the example above: YOURASHOST - host (IP or DNS name) is the location of your application server. If you run HTTP demon on the same host as your app server, you can change this to localhost. ASHTTPPORT - port, is the location where your app server will listen for incoming requests. For tomcat this value, by default, is 8080. You can find the value at tomcat/conf/server.xml

In this example, HTTP daemon will work in reverse proxy mode (ProxyRequests Off) and will redirect all requests to tcp port 8080 on localhost. So, the configuration of a virtual host will look like the following:

        <VirtualHost *:80>
                ServerName      Enter your server DNS name here
                RedirectMatch	permanent "^/?$" "/portal/"
		ProxyRequests   Off
		ProxyPass	 "/" http://localhost:8080/
		ProxyPassReverse "/" http://localhost:8080/
        </VirtualHost>

For more detail about mod_proxy, review this documentation

As described above, the 'glue' method can be implemented in two ways:

With the first method, you only need the HTTP demon and application server, but settings are limited. With the second method, you can obtain much richer settings, but you will need to download and install additional modules for HTTP Daemon that are not included in the default package.

Make sure that mod_proxy_ajp.so is included in the list of loadable modules. Add the following to your virtual host configuration setting:

ProxyPass / ajp://localhost:8009/

In this example, the app server is located on the same host as the Apache HTTP daemon, and accepts incoming connections on port 8009 (the default setting for tomcat application server). \ A full list of virtual host configurations can be found here:

        <VirtualHost *:80>
                ServerName      Enter your server DNS name here
                RedirectMatch	permanent "^/?$" "/portal/"
		ProxyRequests   Off
		ProxyPass	/ ajp://localhost:8009/
        </VirtualHost>

  1. Download AJP connector module from here

  2. Move the downloaded mod_jk.so file into HTTPD's module directory. For example: /etc/httpd/modules (this may be different, depending on the OS)

  3. Create the configuration file for module mod_jk.conf

	LoadModule    jk_module  modules/mod_jk.so
	<IfModule jk_module>
	  # ---- Where to find workers.properties
          JkWorkersFile   conf.d/workers.properties
	  # ---- Where to put jk logs
	  JkLogFile       logs/mod_jk.log
	  # ---- Set the jk log level [debug/error/info]
	  JkLogLevel    info
	  # ---- Select the timestamp log format
	  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
	  JkRequestLogFormat "%w %R %T"
	  # ---- Send everything for context /examples to worker named worker1 (ajp13)
	  JkMountFileReload       "0"
	</IfModule>

You can find more details in the Tomcat docs

  1. Place the mod_jk.conf file into the directory where other configuration files for Apache HTTP Demon are located. For example, /etc/httpd/conf.d/

  2. Create a workers.properties file, which defines AJP workers for HTTP demon.

	worker.list=status, WORKER_NAME
	# Main status worker
	worker.stat.type=status
	worker.stat.read_only=true
	worker.stat.user=admin
	# Your AJP worker configuration
	worker.WORKER_NAME.type=ajp13
	worker.WORKER_NAME.host=localhost
	worker.WORKER_NAME.port=8109
	worker.WORKER_NAME.socket_timeout=120
	worker.WORKER_NAME.socket_keepalive=true

Note

In example above you can change WORKERNAME to any value.

  1. Place this file in the same directory as the mod_jk.conf file.

  2. Update the virtual host configuration:

        <VirtualHost *:80>
                ServerName      Enter your server DNS name here
                RedirectMatch	permanent "^/?$" "/portal/"
		ProxyRequests   Off
                JkMount         /*	WORKER_NAME
        </VirtualHost>

The session-timeout is a concept that the web server uses to define a time period in which a session is valid/accessible. In a portal environment such as eXo Platform, it is highly recommended that all web applications have the same session timeout value:

The session timeout is configurable individually for each web application in web.xml file:

<!-- ==================== Default Session Configuration ================= --> 
   <!-- You can set the default session timeout (in minutes) for all newly   --> 
   <!-- created sessions by modifying the value below.                       --> 

   <session-config> 
      <session-timeout>30</session-timeout> 
   </session-config>

In the Tomcat bundle, this file is located at $TOMCAT_HOME/conf/web.xml. To configure the session-timeout of Server Tomcat, do as follows:

  1. Stop the server shutdown.sh

  2. Open the file web.xml

  3. Change the value of the session-timeout

  4. Save

  5. Restart (gatein.sh)

In the Jboss, this file is located at $Jboss_home/server/default/deployers/jbossweb.deployer/web.xml. To configure the session-timeout of Server Jboss, do as follows:

  1. Stop the server shutdown.sh

  2. Open the file web.xml

  3. Change the value of the session-timeout

  4. Save

  5. Restart (run.sh)