Chapter 3. Installation

All you require in order to start using JTrac is Java 8 (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.8 or greater, you are ready to download and run JTrac.

You can download Java from here: https://adoptium.net/.

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.

You can use the "stop.bat" script to stop the application. The "start.int" file configures the Jetty server to use port 8888 which you can easily change by editing "start.int" (search for "jetty.http.port=8888"). You may need to do this if JTrac does not start because another server (like Apache, IIS or Tomcat) is already running on port 8888.

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.

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.

JTrac also provides other settings for an individual headline (jtrac.header.text) and an individual logo on the right-hand side (jtrac.header.text). If no logo is set the original JTrac logo is shown. Various background colors (jtrac.color.*) and some other options can be set here as well. If the jtrac.edit.item configuration item is set to true, people may edit their own items after creating it; otherwise, no change is possible. Admins are always able to change the original item text.

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 3.1 compliant container. For example, if you have Apache Tomcat 8.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.

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.

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

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

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 default 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 edit the values above to match the settings of a database that you wish to use. Please refer to your database JDBC driver documentation for the values needed for the driver and URL. You can look up the Hibernate dialect corresponding to your database type from this list. When using a custom database such as MySQL, you have to create an empty database before starting JTrac. When JTrac starts, it will connect to the configured database and create the schema (database tables) if not already present.

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 placing the jar file in 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. It assumes that you have created a new database called "jtrac". 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 HikariCP connection pool used internally by JTrac is configured to refresh stale database connections.

You should also ensure that the database default character-set encoding is set correctly for your requirements and UTF-8 is normally recommended. When setting up a fresh JTrac installation on a non-default database such as MySQL, it is best that you do a small test by creating an item with say Japanese or Chinese text in the summary or description. Verify that special characters display correctly when viewing the item. Also check if e-mail notifications look okay as well.

If your database default character set is not what is expected you can consider setting it explicitly for the database to be used by JTrac. For example if using MySQL, you can create the database specifying the character set to be used like this:

create database jtrac charset utf8;
                

And then you can force the encoding used by database connections in the JDBC URL. This is how the corresponding line in "jtrac.properties" will look like:

database.url=jdbc:mysql://localhost/jtrac?useEncoding=true&characterEncoding=utf8
                

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.

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.

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.

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:

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.

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.

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