Chapter 3. Installation

3.1. Prerequisites

All you require in order to start using JTrac is Java 5 (or higher). Only a JRE (Java Runtime Environment) is required and not the full-blown JDK (Java Development Kit).

There is a good chance that Java is already installed on your system and you can verify whether it is ready to run JTrac by opening a command prompt and typing the following command:


java -version
                

If the system responds with a java version that is 1.5 or greater, you are ready to download and run JTrac.

You can download Java from here: http://www.java.com/download.

3.2. Quick Installation

Once you have Java you can start using JTrac right away because you do not need to configure a web-application server or a database. JTrac embeds both of these (Jetty and HSQLDB) to make it easy for you to evaluate JTrac.

  • First, download the latest release from the JTrac downloads area

  • Extract the zip file into a directory of your choice

  • Double-click or run "start.bat" to start JTrac

  • Point your web-browser to http://localhost/jtrac

  • Sign on with the user name "admin" and password "admin"

  • Start using JTrac

You can use the "stop.bat" script to stop the application. The "start.bat" file configures the Jetty server to use port 80 which you can easily change by editing "start.bat". You may need to do this if for example JTrac does not start because a web-server (like Apache or IIS) is already running on port 80.

Remote users should be able to access JTrac over the network by using the machine name instead of "localhost" in the URL shown above. If there is a problem, it could be due to a firewall running on the machine where JTrac is installed - and you may have to reconfigure things so that for example "java.exe" is not blocked.

3.2.1. Notes for Linux / Unix users

If you are not on Windows, you may want to rename the start and stop *.bat files to e.g. *.sh for Linux (*.bat is reported to work for Ubuntu). The commands within the batch files will work unchanged as long as Java has been installed correctly i.e. "java" is in the PATH and it is the expected 1.5 or greater version. You may need to do things like apply executable permissions to the batch files on Linux, e.g. "chmod +x *.bat". And also - unless you have "root" permissions, you may face problems starting services on port 80 etc.

3.2.2. Security and Backup

For security reasons, it is best that you change the default "admin" password after installing JTrac, especially if you are going to make the application accessible on a public-facing web-site over the internet.

JTrac by default will use a "data" directory that will be automatically created within the root folder "jtrac". The data directory will contain the files needed by HSQLDB (the embedded database) as well as hold uploaded attachments. When using JTrac in production, this is the location that you should consider backing-up on a regular basis.

3.3. Settings

For e-mail notifications to work, an SMTP server needs to be configured in JTrac. Users who have the ADMIN role will be able to access the JTrac configuration settings screen from a link on the "OPTIONS" screen. Note that you will need to provide values for the "mail.from" and the "jtrac.url.base" properties also, for things like the hyperlinks within e-mail to work properly. JTrac also supports mail servers that require authentication or secure connections using SSL. You can refer the descriptions of the available configuration property settings available from the settings screen as shown below.

If you have trouble getting e-mail to work, one of the things to watch out for is whether there is any firewall blocking the communication between JTrac and the mail server - for example you may have a firewall runnning on the machine where JTrac is installed. It is very common for mail servers to be configured to prevent mail-relay requests from unknown applications or IP addresses so you may need to check with your mail server administrator.

The JTrac settings screen where you can configure an e-mail / SMTP server

JTrac also can lookup and use a JNDI mail session (javax.mail.Session) if required. If you provide a JNDI name, JTrac will ignore the SMTP server details provided.

3.4. Using only the WAR file

JTrac is designed so that you can be up and running by just deploying the WAR file into your existing web-application server. Note that you need a servlet 2.4 compliant container. For example, if you have Apache Tomcat 5.5.X, you can either copy the WAR file into the [tomcat.home]/webapps folder or choose to upload the WAR file through the Tomcat console.

JTrac saves database information and uploaded attachments into a directory on the server. This directory is logically called the "jtrac.home". When you do a "quick-install" of JTrac by just deploying the WAR file, JTrac creates a ".jtrac" folder in the user home folder and uses that location as the home directory. This is great for quickly evaluating JTrac but when you actually use JTrac in production you should configure the JTrac home directory as a location that can easily be backed-up for example.

3.5. Custom Installation

To customize the location of "jtrac.home" you have the following three options. On startup, JTrac tries to detect the value of "jtrac.home", and checks the following configuration options in the order listed below.

3.5.1. Edit the "jtrac-init.properties" file

If you explode (unzip) the WAR file, you can edit the /WEB-INF/classes/jtrac-init.properties file and customize the location of "jtrac.home". Note that you can choose to deploy JTrac as an exploded-war and it is not mandatory that you re-package (zip) the WAR file after editing "jtrac-init.properties".

3.5.2. Set a Servlet context parameter

For example you can specify the jtrac.home using the Tomcat administration console or as follows using a <Context> parameter.

                                                
<Context docBase="${catalina.home}/jtrac/jtrac.war">
    <Parameter name="jtrac.home" value="C:/data/jtrac_home"/>
</Context>              
                    

3.5.3. Set a System / JVM parameter

If you can easily set a system property called "jtrac.home" within the environment of your application server then you don't need to edit the WAR file. Please look at the contents of "start.bat" to see an example of how the appropriate JVM (Java Virtual Machine) parameters can be set when deploying JTrac. For example, if you are using Apache Tomcat 5.5.X, you can set an environment variable called JAVA_OPTS before invoking the startup script (startup.bat / startup.sh). Here is an example for Tomcat 5.5.X on Windows:


set JAVA_OPTS=-Djtrac.home=C:/data/jtrac_home -Dfile.encoding=UTF-8
                    

If "jtrac.home" has not been configured in any of the above ways, JTrac will create a folder called ".jtrac" in the user home directory and proceed to use that as "jtrac.home".

3.6. Using a different database such as MySQL

You can configure the database that JTrac uses by editing the "jtrac.properties" file that JTrac expects within the "jtrac.home" folder. Note that if JTrac does not find a "jtrac.properties" file in the expected location, JTrac creates a fresh one which is pre-configured for HSQLDB. The contents of this file are as follows:


database.driver=org.hsqldb.jdbcDriver
database.url=jdbc:hsqldb:file:${jtrac.home}/db/jtrac
database.username=sa
database.password=
hibernate.dialect=org.hibernate.dialect.HSQLDialect
hibernate.show_sql=false
                

You can change the database values and the hibernate dialect to match the settings of a database that you have already. When JTrac starts, it will connect to the database and create the schema if one does not already exist.

If you edit the "jtrac.properties" file, ensure that there are no trailing spaces in the entries shown above (especially when cutting and pasting from somewhere). This can save you a lot of frustration!

Don't forget to make the database driver available for the web-application. If you are using the bundled Jetty web-app server, this is as simple as copying the jar file into the "lib" folder along with the jetty jar files. If you are using Tomcat, you can either place the jar file under "shared/lib" or within the "/WEB-INF/lib" folder of the "jtrac" (exploded) WAR itself.

Given below is a sample jtrac.properties file for MySQL. Using the default "root" user is obviously not advisable from a security point of view and you should try and have a separate user for the database used by JTrac.


database.driver=com.mysql.jdbc.Driver
database.url=jdbc:mysql://localhost/jtrac
database.username=root
database.password=
hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.show_sql=false
                

For MySQL, do not use the "autoReconnect=true" parameter in the MySQL URL, this is not recommended by the MySQL team. The Apache DBCP connection pool used internally by JTrac is configured to refresh stale database connections.

The default query to test idle database connections is "SELECT 1". This has been reported to not work for databases such as Derby and Progress because they consider this invalid SQL. You can customize the validation query by adding a "database.validationQuery" property in "jtrac.properties. If you set the validation query to an empty string, this effectively disables the periodic testing of idle database connections that Apache DBCP performs.

3.7. Using a JNDI Datasource

You can provide a JNDI datasource name as an additional property called "database.datasource.jndiname" in the "jtrac.properties" file. JTrac will ignore the other database properties in this case.

3.8. Configuring LDAP Authentication

A couple of extra entries in "jtrac.properties" are required in order to configure LDAP authentication. JTrac will attempt LDAP authentication if an "ldap.url" config entry is present.

                    
ldap.url=ldap://myldaphost
ldap.searchBase=DC=foo,DC=bar,DC=org
                

The following additional entry is recommended if you are using Active Directory. This switches on an LDAP optimization that is specific to Active Directory.

                    
ldap.activeDirectoryDomain=MYDOMAIN
                

The benefit of LDAP authentication is that users can sign-on to JTrac by using their existing LDAP credentials (username and password). At the moment, LDAP support is limited to authentication and not authorization. Users still have to be created by an administrator and mapped to the relevant Spaces using the JTrac administration screens before they can start using JTrac.

3.9. Integrating with CAS for Single Sign On

In order to integrate JTrac with CAS you have to edit a couple of XML files within the "WEB-INF" folder ('web.xml' and 'applicationContext-acegi-cas.xml'). The changes that you need to make are described below.

3.9.1. Changes to web.xml

  • Change "applicationContext-acegi.xml" to "applicationContext-acegi-cas.xml". This appears towards the start of the file in the 'contextConfigLocation' context-param.

  • Uncomment the filter and filter-mapping XML for the 'acegi' FilterToBeanProxy

  • Uncomment the servlet and servlet-mapping XML for the 'casProxy' ProxyTicketReceptor. You should also uncomment the associated context-param called 'edu.yale.its.tp.cas.proxyUrl' and customize the value for your environment.

3.9.2. Changes to applicationContext-acegi-cas.xml

In the XML corresponding to bean id "casProxyTicketValidator" - edit the following property values to suit your environment:

  • casValidate

  • proxyCallbackUrl

  • trustStore

  • loginUrl

  • logoutUrl

For more details and troubleshooting, you can refer to the Acegi documentation on CAS integration.

3.10. Installing as a Windows Service

Note that this approach can reportedly apply to other operating systems. If you have been able to do this successfully on Linux or Mac environments, please consider contributing some documentation on this.

If you choose to use the bundled Jetty web-application server, you can easily install JTrac as a Windows service so that it can start automatically when the host machine is switched on. One of the big advantages of this is that the console window will be invisible and will run in the background. You can therefore avoid the possibility of the Jetty server getting terminated because somebody decided to close "that pesky DOS Window that gets in the way". Having JTrac start automatically without requiring someone to log-in is ideal when you have a server that may be restarted occasionally due to power outages or maintenance.

JTrac can be configured as a Windows service by using the Java Service Wrapper project. For convenience, the JTrac distribution contains a "wrapper.conf" file in the "etc" folder that is pre-configured for the Java Service Wrapper. But first you have to download the Java Service Wrapper distribution separately. Note that the Java Service Wrapper project supports other operating systems such as Linux or Mac also.

Place some of the files from the Java Service Wrapper distribution into the JTrac folder structure as follows:

  • From the "bin" folder, copy "wrapper.exe" to the "jtrac" root folder

  • From the "lib" folder, copy "wrapper.jar" and "wrapper.dll" into the "jtrac/etc" folder

To install JTrac as a windows service, open a command prompt, change to the "jtrac" directory (where you extracted the JTrac distribution) and run the following command:


wrapper.exe -i etc/wrapper.conf
                

This will install a windows service called "JTrac-Jetty". You can now go to the Windows - Control Panel :: Administrative Tools :: Services dialog to start the "JTrac-Jetty" service. Note that this service is configured to automatically start when Windows starts, by default. To remove the service, you can use the following command:


wrapper.exe -r etc/wrapper.conf
                

The "wrapper.conf" file in the "etc" folder can be modified in case you need JTrac to run on a different port from the default (80). Look for the "-Djetty.port=80" entry. When running as a service under the Java Service Wrapper, you can look at the "wrapper.log" file in the "jtrac/logs" folder for troubleshooting.

3.11. What to Backup

Although in practice JTrac has been found to be extremely stable in production - to safeguard against hardware failures, you should regularly backup the database and stored attachments. If you are using JTrac with the embedded HSQLDB database, backing up the contents of "jtrac.home" will be sufficient. The HSQLDB data will be stored as files in a directory called "db" under the JTrac home.

If you are using the JTrac distribution as-is, i.e. if you are using the bundled Jetty application server - the JTrac home directory will be called "data" and this is created automatically under the folder where you un-zipped JTrac.

Of course, if you are using a different database you will have to backup the database separately. The "jtrac.home" would still need to be backed up because this is where uploaded attachments are stored.

3.12. Upgrading

Please refer to the "upgrading" section of this document.