Deployment modes

Three deployment modes are available.

Portlet deployment

This deployment is proposed for portal administrators, it deploys esup-helpdesk as a JSR-168 portlet, in order to execute it within a JSR-168 compliant portal (uPortal, Liferay, infoglue, ...).

If you are no portal administrator or you do not know what a portlet is, select a servlet or quick-start deployment.

Servlet deployment

This deployment is proposed for deployers who want to run the application into an existing servlet container (such as Tomcat).

If you do not know what a servlet is or if you do not have a J2EE runtime available, select a quick-start deployment.

Quick-start deployment

This deployment allows esup-helpdesk to run as a stand-alone application (a Tomcat instance is embedded).

It can be used in order to test the application, but some deployers (especially those who d not have J2EE competences) run in production this way; quick-starts are full-featured applications.

Requirements

Installing esup-helpdesk needs a few requirements.

• esup-helpdesk is provided as a zip file that contains all the sources. The sources must be compiled, which needs a Java Development Kit (a Java Runtime Environment is not enough).
• Installation commands and asynchroneous tasks are run using ant.
• esup-helpdesk is configured by default to connect to a MySql database; Hibernate allows the usage of any other database manager (see Configuring the database connection).

Unix requirements

Java

Any Unix administrator knows how to install a JDK, embedded in most distributions. If not, download from http://java.sun.com/javase/downloads/index.jsp.

Ant

If ant is not available as a package (RPM or any), it can be downloaded from http://ant.apache.org/bindownload.cgi  and installed for instance in /usr/local/.

Java/ant environment variables

In order to simplify administration commands and asynchroneous tasks (see 03 Administration), deployers may create in the folder /etc/profile.d the following java.sh script (adapt to your own configuration) :

export JAVA_HOME=/usr/java/jdk1.6.0_05
export ANT_HOME=/usr/local/apache-ant-1.7.0
export PATH=$PATH:$JAVA_HOME/bin:$ANT_HOME/bin

Windows requirements

TODO Any Windows deployer?

Download

The last release can be downloaded at http://helpdesk.esup-portail.org/current (previous releases are at http://helpdesk.esup-portail.org).

Uncompressing the sources

Uncompress the zip file you have downloaded to your filesystem, for instance in /usr/local/helpdesk/src. Uncompressing esup-helpdesk-3.y.z-t.zip creates the folder usr/local/helpdesk/src/esup-helpdesk-x.y.z.

Successive versions must be installed at the same location on the filesystem in order to ease upgrades.

Deployment properties (build.properties)

At first, edit the configuration file /build.properties to set the properties that tell how the application should be installed.

Once these properties set (see below for details), the behaviour of the application at runtime must be configured (see 01 Configuration).

When changing the deployment mode, it is recommended to clean everything (ant clean) before deploying again.

Common properties (any deployment)

Whatever the deployment mode selected, property custom.recover.files must be set.

custom.recover.files

Property custom.recover.files is used when upgrading the application to recover the deployer's customizations, for instance:

custom.recover.files= properties/domain/xmlDepartmentSelection.xml

Quick-start deployments

quick-start

Just tell the it is a quick-start deployment this way:

quick-start=true

All the other properties are optional.

Optional properties

Properties tomcat.host, tomcat.port and tomcat.shutdown-port can be used in order to configure the embedded Tomcat (default values below):

#tomcat.port=8080
#tomcat.shutdown-port=8009
#tomcat.host=localhost

When using a quick-start deployment, the application is deployed into the folder /deploy; a Tomcat instance is installed automatically and configured to point to the application context.

Portlet deployments

deploy.type

Tell that it is a portlet deployment:

deploy.type=portlet

deploy.home

Tell where the application will be deployed to be executed by the portal, typically in a webapps folder of an existing portal:

deploy.home=/usr/local/uPortal/webapps/esup-helpdesk

This path should be used by the portal administrator to configure the portlet context. Typically (tomcat/conf/server.xml):

<Host name="localhost"
    appBase="webapps" unpackWARs="true"
    autoDeploy="true" xmlValidation="false"
    xmlNamespaceAware="false">
    <Context path="/esup-helpdesk"
	docBase="/usr/local/uPortal/webapps/esup-helpdesk"
	crossContext="true" reloadable="true">
      <Manager pathname="" />
    </Context>
</Host>

Servlet deployments

deploy.type

Tell that it is a servlet deployment:

deploy.type=servlet

deploy.home

Tell where the application will de deployed to be executed by the servlet container, typically in the webapps folder of an existing Tomcat:

deploy.home=/usr/local/tomcat/webapps/esup-helpdesk

This path should be used to configure the servlet context. Typically (tomcat/conf/server.xml):

<Service name="Catalina">
    <Connector 	port="8080"
	maxHttpHeaderSize="8192" maxThreads="150"
	minSpareThreads="25" maxSpareThreads="75"
	enableLookups="false" redirectPort="8443"
	acceptCount="100" connectionTimeout="20000"
	disableUploadTimeout="true" emptySessionPath="true" />
    <Engine name="Catalina" defaultHost="helpdesk.domain.edu">
        <Host name="helpdesk.domain.edu"
    	    appBase="webapps" unpackWARs="true"
	    autoDeploy="true" xmlValidation="false"
	    xmlNamespaceAware="false">
	    <Context
		path="" docBase="/usr/local/tomcat/webapps/esup-helpdesk"
		crossContext="true" reloadable="false">
                <Manager pathname=""
		    className="org.apache.catalina.session.StandardManager" />
            </Context>
        </Host>
    </Engine>
</Service>