Menu
▾
▴
[jtrac-svn] SF.net SVN: j-trac:[1408] trunk/jtrac
|
From: <udi...@us...> - 2021-11-09 09:20:21
|
Revision: 1408
http://sourceforge.net/p/j-trac/code/1408
Author: udittmer
Date: 2021-11-09 09:20:17 +0000 (Tue, 09 Nov 2021)
Log Message:
-----------
user HTML number inputs in settings; start updating documentation
Modified Paths:
--------------
trunk/jtrac/doc/src/index.xml
trunk/jtrac/src/main/java/info/jtrac/domain/Config.java
trunk/jtrac/src/main/java/info/jtrac/wicket/ConfigFormPage.html
trunk/jtrac/src/main/java/info/jtrac/wicket/ConfigFormPage.java
trunk/jtrac/src/main/java/info/jtrac/wicket/CustomFieldsFormPanel.java
Added Paths:
-----------
trunk/jtrac/src/main/java/org/
trunk/jtrac/src/main/java/org/apache/
trunk/jtrac/src/main/java/org/apache/wicket/
trunk/jtrac/src/main/java/org/apache/wicket/markup/
trunk/jtrac/src/main/java/org/apache/wicket/markup/html/
trunk/jtrac/src/main/java/org/apache/wicket/markup/html/form/
trunk/jtrac/src/main/java/org/apache/wicket/markup/html/form/DateField.java
trunk/jtrac/src/main/java/org/apache/wicket/markup/html/form/NumberField.java
Modified: trunk/jtrac/doc/src/index.xml
===================================================================
--- trunk/jtrac/doc/src/index.xml 2021-11-08 13:03:51 UTC (rev 1407)
+++ trunk/jtrac/doc/src/index.xml 2021-11-09 09:20:17 UTC (rev 1408)
@@ -1,1910 +1,1905 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
-
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
--->
-
-<book>
- <bookinfo>
- <title>JTrac</title>
- <subtitle>User / Developer Guide</subtitle>
- <releaseinfo>2.2.0</releaseinfo>
- <authorgroup>
- <author>
- <firstname>Peter</firstname>
- <surname>Thomas</surname>
- </author>
- <author>
- <firstname>Manfred</firstname>
- <surname>Wolff</surname>
- </author>
- </authorgroup>
- </bookinfo>
-
- <toc/>
-
- <preface id="preface">
- <title>Preface</title>
- <para>
- This document is a reference guide for <ulink url="http://jtrac.info">JTrac</ulink>
- - the generic issue tracking web-application. This document is not only a user-guide
- but can also serve as a reference for developers interested in contributing to JTrac.
- </para>
- <para>
- This documentation has been generated using the DocBook configuration
- used by the <ulink url="http://www.springframework.org">Spring</ulink> development team.
- This particular simplified DocBook helper package was originally developed by Chris Bauer of the
- <ulink url="http://www.hibernate.org">Hibernate</ulink> project. Thanks go out to all those who
- perfected this very handy approach.
- </para>
- </preface>
-
- <chapter id="introduction">
- <title>Introduction</title>
- <sect1 id="introduction-about">
- <title>About</title>
- <para>
- JTrac is a generic issue-tracking web-application that can be easily customized by adding
- custom fields and drop-downs. Features include customizable workflow, field level permissions,
- e-mail integration, file attachments and a detailed history view.
- </para>
- <para>
- JTrac was created after the author felt that he could write a much better alternative to a
- commercial defect tracking tool that he was having to use. Development started in 2004.
- JTrac is ideal for issue tracking or bug-tracking, but it has been designed to be generic
- and you can define custom fields to track almost anything you need.
- </para>
- <para>
- JTrac development used to be hosted at <ulink url="https://jtrac.dev.java.net"/> but moved to SourceForge
- in early 2006. The older working version was based on Spring MVC, Spring JDBC and MS Access and is not being
- maintained any more. JTrac 2.0 uses Java 5.0 features and was completely re-written to use
- <ulink url="http://www.hibernate.org/">Hibernate</ulink> for persistence and the
- <ulink url="http://www.acegisecurity.org/">Acegi Security</ulink> framework for Spring. The presentation
- layer for version 2.0 was mainly using
- <ulink url="http://opensource.atlassian.com/confluence/spring/display/WEBFLOW/Home">Spring WebFlow</ulink>
- but as of early 2007 (version 2.1.0 onwards) JTrac
- <ulink url="http://ptrthomas.wordpress.com/2007/03/02/wicket-impressions-moving-from-spring-mvc-webflow/">switched to </ulink>
- using the <ulink url="http://wicket.apache.org/">Apache Wicket</ulink> framework.
- </para>
- <para>
- JTrac is extremely easy to install and the only pre-requisite is a Java 5 (or higher) Runtime Environment.
- You can be up and running in seconds because JTrac comes bundled with a small-footprint web-application
- server called <ulink url="http://jetty.mortbay.org/">Jetty</ulink> and an embedded database called
- <ulink url="http://www.hsqldb.org/">HSQLDB</ulink>. Please refer to the
- <link linkend="installation">installation</link> section of this documentation for details.
- You can also choose to drop the WAR file into an application server of your choice and start using JTrac right away.
- </para>
- </sect1>
-
- <sect1 id="introduction-releasenotes">
- <title>Release Notes: Version 2.1.0</title>
- <para>
- There are no database changes between version 2.0 and 2.1.0. Instructions on how to upgrade are
- available in the "<link linkend="upgrading">upgrading</link>" section of this document. The bundled
- Jetty web-app server has been upgraded from version 6.0.2 to 6.1.1 but it is not mandatory that you
- upgrade.
- </para>
- </sect1>
-
- <sect1 id="introduction-releasenotes-2_2">
- <title>Release Notes: Version 2.2.0</title>
- <para>
- There are no database changes between version 2.1.0 and 2.2.0. Instructions on how to upgrade are
- available in the "<link linkend="upgrading">upgrading</link>" section of this document.
- </para>
- <para>
- There where some minor changes and bugfixes:
- <itemizedlist>
- <listitem>
- <para>It is possible to configure an individual header and an individual logo for your own JTrac.</para>
- </listitem>
- <listitem>
- <para>Errors that were occured because of missing language ressources are fixed.</para>
- </listitem>
- <listitem>
- <para>Some email-issues e.g. sending duplicate mails are fixed.</para>
- </listitem>
- </itemizedlist>
- For details see the <ulink url="https://sourceforge.net/projects/j-trac/">different tracker at
- the sourceforge website.</ulink>
- </para>
- </sect1>
- </chapter>
-
- <chapter id="features">
- <title>Features</title>
- <para>
- JTrac has all the features that you would expect from a standard issue-tracking application such as
- support for file-attachments and e-mail integration. JTrac offers powerful customization options,
- especially in the areas of workflow and field-level permissions and compares well to even
- commercial tools.
- </para>
- <sect1 id="features-easytoinstall">
- <title>Easy to Install</title>
- <para>
- One of the useful features of JTrac is that it is distributed with an embedded web-application server
- (<ulink url="http://jetty.mortbay.org/">Jetty</ulink>) that has a very small footprint.
- If you have Java 5 installed you can be up and running after downloading and extracting JTrac - by
- simply using the provided start and stop scripts. JTrac scans its environment on startup and if a
- configured database is not detected, <ulink url="http://www.hsqldb.org/">HSQLDB</ulink> is used by
- default.
- </para>
- <para>
- If you already have a web-application server that you wish to use (such as
- <ulink url="http://tomcat.apache.org/">Tomcat</ulink>), you can just drop in the WAR file
- provided and sign on into the application straight-away.
- </para>
- <para>
- You can refer the <link linkend="installation">installation</link> section of this document for
- more details. JTrac uses <ulink url="http://www.hibernate.org">Hibernate</ulink> and so it can
- use any database <ulink url="http://www.hibernate.org/80.html">supported by Hibernate.</ulink>
- </para>
- </sect1>
- <sect1 id="features-customfields">
- <title>Custom Fields</title>
- <para>
- JTrac can be used to effectively track various kinds of things such as Bugs, Action Items and Tasks.
- You can easily add the following types of custom fields to a tracker Project (Space):
- <itemizedlist>
- <listitem>
- <para>Drop Down List</para>
- </listitem>
- <listitem>
- <para>Free Text Field</para>
- </listitem>
- <listitem>
- <para>Date Picker</para>
- </listitem>
- <listitem>
- <para>(Decimal) Number</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/custom-fields.png"/>
- </imageobject>
- <caption>
- <para>Setting up custom fields for a project</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- There is a limit to how many custom fields of each type that you can configure for a Space.
- These limits have been set after careful consideration and would very rarely fail to suffice.
- They are as follows: Drop Down - 10, Free Text - 5, Numeric - 3, Date/Time - 3.
- </para>
- <para>
- The screenshot below shows how creating a new item would look like for the typical
- project (space) where 'Severity', 'Module', 'Type' and 'Priority' have been defined
- as custom fields.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/item-create.png"/>
- </imageobject>
- <caption>
- <para>Creating a new item</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-customworkflow">
- <title>Custom Workflow</title>
- <para>
- Each tracker project that you create can have a different workflow. JTrac allows for
- complete customization of the tracker-item lifecycle, right down to the names of
- each intermediate state. It is possible to create very sophisticated workflows and a visual
- "map" of the workflow being edited is displayed below the state-transition toggle-buttons
- to make it easier to manage.
- </para>
- <para>
- The default workflow shown below is ideal if you simply want to track issues with just
- two states - Open and Closed. However, with just a few mouse clicks, you can turn this into
- a complex workflow involving multiple states.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/custom-workflow-before.png"/>
- </imageobject>
- <caption>
- <para>Default workflow - before customization</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/custom-workflow-after.png"/>
- </imageobject>
- <caption>
- <para>Example of a workflow - after customization</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- You can even configure whether or not changing of values is permitted given the current state
- within the workflow - and that too at a field-level. This flexibility allows for some
- interesting possibilities. For example, assume that you want to maintain a "percentage complete"
- field that can be updated at any time during the life-cycle of an item. The screenshot below
- demonstrates how you can set up a drop down field called "% Complete":
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/percent-complete-field.png"/>
- </imageobject>
- <caption>
- <para>Setting up of a drop down custom field called "% Complete"</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- Then when customizing the roles and field-level permissions, all you need to do is specify that
- the "% Complete" field is editable even when the status is "Open".
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/percent-complete-roles.png"/>
- </imageobject>
- <caption>
- <para>Making a custom field editable when updating an item (after new item has been created)</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- This results in the "% Complete" field being available for updating whenever anyone views an item
- with a status of "Open". Notice also how the "% Complete" field is added as a column to the "History"
- section so that the complete history of changes to this custom field can be viewed.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/percent-complete-history.png"/>
- </imageobject>
- <caption>
- <para>Example of a custom field that can be updated even when status is "Open"</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-history">
- <title>Detailed History View</title>
- <para>
- JTrac provides a very detailed history view that completely captures all comments or status
- changes for an item. The history can be seen when viewing an item as shown above.
- </para>
- </sect1>
- <sect1 id="features-attachments">
- <title>Attachments Support</title>
- <para>
- You can upload file attachments at the time of creating of an item or as many times
- as required after an item has been created.
- </para>
- </sect1>
- <sect1 id="features-customroles">
- <title>Custom Roles</title>
- <para>
- JTrac customization does not stop at workflow - you can also define different roles for each tracker
- project that you set up. This allows for power and flexibility. For example you could enforce that
- a "DEVELOPER" role can only mark "Assigned" items as "Fixed" and that only a "TESTER" role has the
- power to mark a "Fixed" item as "Closed". You can even disallow selected roles from being able to
- create new items. JTrac gives you complete control over the workflow and you can easily tweak it
- to fit your existing process rather than the other way around.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/custom-roles.png"/>
- </imageobject>
- <caption>
- <para>Example of workflow where each role has clearly defined responsibilities.</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- In the example above, the roles highlighted in red on the visual "map" of the workflow being edited
- mean that at these points in the workflow - a user with the given role can assign only to other roles.
- So in this case, the TESTER can assign a New item only to a DEVELOPER role and not another TESTER.
- And when an item is in the "Assigned" state, a DEVELOPER can only assign to a TESTER when changing the
- status to "Fixed" or "Rejected".
- </para>
- <para>
- Field-level permissions can be mapped to roles which allows for even more flexibility.
- For example, you can set a project up so that only a "MANAGER" can change the "Severity" level
- after a bug is submitted. JTrac makes it possible for you to define very complex workflows, complete
- with both Status and Role dependent field-level permissions, and you can do all this within a
- single admin screen.
- </para>
- </sect1>
- <sect1 id="features-search">
- <title>Search Custom Fields</title>
- <para>
- The intuitive search screen (shown below) allows for easy execution of common queries such as
- find all items "logged by" or "assigned to" a user (or users). JTrac allows for filtering even
- on custom fields.
- </para>
- <para>
- You can navigate back to the search setup screen from the search results screen and have the
- search parameters still active. This is useful when trying to tweak complex queries by
- trial and error.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/search.png"/>
- </imageobject>
- <caption>
- <para>The search screen - which allows filtering on custom fields</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-dashboard">
- <title>Dashboard</title>
- <para>
- The default view when you log into JTrac is a very handy dashboard view that provides the most
- frequently used statistics at a glance. You can click on any of the numbers to immediately bring up
- the search results view listing the items matched. For example, clicking on the count of items
- "Logged By Me" would immediately display the list of items initiated by the currently logged in user.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/dashboard.png"/>
- </imageobject>
- <caption>
- <para>Statistics at a glance and search results available with just one click</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- For each Space, you can also drill-down to a finer level of detail by clicking on the right-arrow
- 'expand' icon. This expands the dashboard rows so that you can see a break-up of item counts, not only by
- whether 'logged by me' / 'assigned to me' - but against the custom workflow states defined for
- the Space as well. Again, it is possible to directly navigate to the items by clicking on the dashboard numbers.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/dashboard-expanded.png"/>
- </imageobject>
- <caption>
- <para>Expanded statistics for a Space showing counts by workflow status</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-searchall">
- <title>Search Across All Projects</title>
- <para>
- In addition to be able to search within a single space (project) JTrac allows for searching across
- all (or a sub set of) projects that a user is mapped to. For example, in the screenshot of the
- dashboard above, there are two projects. The "SEARCH" link at the top of the page (as well as the "search"
- link on the "totals" row) would bring up the search wizard that can search across all (or a subset of)
- the spaces assigned to the currently logged in user.
- </para>
- </sect1>
- <sect1 id="features-textsearch">
- <title>Full Text Search</title>
- <para>
- The summary and even the detailed descriptions of items are indexed and can be searched.
- Note that if you are upgrading or migrating databases, you may need to "re-index" which
- is an option available to admin users.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/full-text-search.png"/>
- </imageobject>
- <caption>
- <para>Lucene powered full text search with wildcard support</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-excel">
- <title>Export to Excel</title>
- <para>
- JTrac is able to export the results of any search (or all items in a Space) as an Excel Sheet.
- The link for this appears at the top right of the search results screen.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/excel-link.png"/>
- </imageobject>
- <caption>
- <para>Download search results as an excel sheet</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- One the data is in a spreadsheet, it is very easy to analyze data and do things
- like creating pivot-tables and charts. Many users use the 'export to Excel' feature
- to fulfil custom reporting requirements.
- </para>
- </sect1>
- <sect1 id="features-navigation">
- <title>Simple Navigation</title>
- <para>
- Most users will use only five screens in JTrac: Dashboard, Create, View, Search and Results.
- Navigation has been designed with usability and simplicity in mind. A screenshot of the
- search results screen is shown below.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/search-results.png"/>
- </imageobject>
- <caption>
- <para>The search results screen</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-related">
- <title>Cross Referencing of Items</title>
- <para>
- You can establish bi-directional links between items. For example you can mark an item as
- being a "duplicate of" another item. You can easily navigate to related items (and back) when
- viewing any particular item.
- </para>
- <para>
- The option to add related items is available when viewing an item after it is created.
- The navigation is designed so that you have the option to execute a search before selecting an
- item to cross-reference.
- </para>
- </sect1>
- <sect1 id="features-guest">
- <title>Read-Only Access</title>
- <para>
- When setting up a Space you can define whether this space can be viewed by users without
- having to log-in.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/guest-allowed.png"/>
- </imageobject>
- <caption>
- <para>Specify if read-only anonymous access is allowed per-space</para>
- </caption>
- </mediaobject>
- </para>
- </sect1>
- <sect1 id="features-email">
- <title>E-mail Integration</title>
- <para>
- All status changes for an item will trigger e-mail notifications by default.
- You can choose to add multiple users into a "notify list" at the time of raising a new item
- or updating the history for an item.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/notify-list.png"/>
- </imageobject>
- <caption>
- <para>Add multiple users to a "notify list" while creating or updating an item</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- The e-mail content is very nicely formatted HTML and is laid out in the same way as how the screen looks
- within JTrac when viewing an item. Users do not need to get used to a different or possibly
- less pleasing format such as plain-text.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/email-notification.png"/>
- </imageobject>
- <caption>
- <para>Example of an e-mail sent by JTrac</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- Admin users can configure the SMTP / e-mail server that JTrac should use in the
- "<link linkend="installation-settings">Manage Settings</link>" page.
- This page can be accessed from the "OPTIONS" menu. JTrac also can handle an e-mail server that requires
- authentication or even a secure connection over HTTPS.
- </para>
- </sect1>
- <sect1 id="features-i18n">
- <title>Multi-Language Support</title>
- <para>
- JTrac has complete internationalization support and you can change the user interface language instantly
- by editing your user-profile. Adding a translation is very easy and does not require any
- Java development expertise. See <link linkend="dev-translating">this section</link> of the developer
- guide for more details and please consider contributing translations to the JTrac project.
- </para>
- <para>
- JTrac has already been translated into the following languages:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Arabic - ar
- </para>
- </listitem>
- <listitem>
- <para>
- Czech - cs
- </para>
- </listitem>
- <listitem>
- <para>
- German - de
- </para>
- </listitem>
- <listitem>
- <para>
- Greek - el
- </para>
- </listitem>
- <listitem>
- <para>
- Spanish - es
- </para>
- </listitem>
- <listitem>
- <para>
- Spanish (Argentina) - es_AR
- </para>
- </listitem>
- <listitem>
- <para>
- Spanish (Mexico) - es_MX
- </para>
- </listitem>
- <listitem>
- <para>
- French - fr
- </para>
- </listitem>
- <listitem>
- <para>
- Hungarian - hu
- </para>
- </listitem>
- <listitem>
- <para>
- Italian - it
- </para>
- </listitem>
- <listitem>
- <para>
- Japanese - ja
- </para>
- </listitem>
- <listitem>
- <para>
- Korean - ko
- </para>
- </listitem>
- <listitem>
- <para>
- Dutch - nl
- </para>
- </listitem>
- <listitem>
- <para>
- Polish - pl
- </para>
- </listitem>
- <listitem>
- <para>
- Portugese (Brazil) - pt_BR
- </para>
- </listitem>
- <listitem>
- <para>
- Russian - ru
- </para>
- </listitem>
- <listitem>
- <para>
- Russian - ru
- </para>
- </listitem>
- <listitem>
- <para>
- Slovenian - sl
- </para>
- </listitem>
- <listitem>
- <para>
- Swedish - sv
- </para>
- </listitem>
- <listitem>
- <para>
- Chinese (China) - zh_CN
- </para>
- </listitem>
- <listitem>
- <para>
- Chinese (Taiwan) - zh_TW
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect1>
- <sect1 id="features-ldap">
- <title>LDAP / CAS authentication support</title>
- <para>
- JTrac has built-in support for authenticating user credentials against an LDAP or Active Directory server.
- Please refer the <link linkend="installation-ldap">LDAP section</link> of the installation guide for more details.
- </para>
- <para>
- JTrac also has support for integrating with a
- <ulink url="http://www.ja-sig.org/products/cas/">Central Authentication Service</ulink> (CAS) installation.
- The install guide has more details on
- <link linkend="installation-cas">how to configure single sign-on using CAS</link>.
- </para>
- </sect1>
- </chapter>
-
- <chapter id="installation">
- <title>Installation</title>
- <sect1 id="installation-prerequisites">
- <title>Prerequisites</title>
- <para>
- 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).
- </para>
- <para>
- 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:
- </para>
- <para>
- <programlisting>
-
-java -version
- </programlisting>
- </para>
- <para>
- If the system responds with a java version that is 1.5 or greater, you are ready to download and run JTrac.
- </para>
- <para>
- You can download Java from here: <ulink url="http://www.java.com/download"/>.
- </para>
- </sect1>
- <sect1 id="installation-quick">
- <title>Quick Installation</title>
- <para>
- 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 (<ulink url="http://jetty.mortbay.org/">Jetty</ulink> and
- <ulink url="http://www.hsqldb.org/">HSQLDB</ulink>) to make it easy for you to evaluate JTrac.
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- First, download the latest release from
- <ulink url="http://sourceforge.net/project/showfiles.php?group_id=162983&package_id=184104">
- the JTrac downloads area</ulink>
- </para>
- </listitem>
- <listitem>
- <para>Extract the zip file into a directory of your choice</para>
- </listitem>
- <listitem>
- <para>
- Double-click or run "start.bat" to start JTrac
- </para>
- </listitem>
- <listitem>
- <para>Point your web-browser to <ulink url="http://localhost/jtrac"/></para>
- </listitem>
- <listitem>
- <para>Sign on with the user name "admin" and password "admin"</para>
- </listitem>
- <listitem>
- <para>Start using JTrac</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <sect2 id="installation-quick-linux">
- <title>Notes for Linux / Unix users</title>
- <para>
- 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.
- </para>
- <para>
- You can also read this forum thread for more details: <ulink url="http://sourceforge.net/forum/forum.php?thread_id=1971135&forum_id=552477">link</ulink>
- </para>
- </sect2>
- <sect2 id="installation-quick-othernotes">
- <title>Security and Backup</title>
- <para>
- 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.
- </para>
- <para>
- 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 <link linkend="installation-backup">backing-up</link>
- on a regular basis.
- </para>
- </sect2>
- </sect1>
- <sect1 id="installation-settings">
- <title>Settings</title>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- <para>
- <mediaobject>
- <imageobject role="html">
- <imagedata align="center" fileref="../images/settings.png"/>
- </imageobject>
- <caption>
- <para>The JTrac settings screen where you can configure an e-mail / SMTP server</para>
- </caption>
- </mediaobject>
- </para>
- <para>
- 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.
- </para>
-
- <para>
- JTrac provides also other settings for an individual Headline (jtrac.header.text) and an
- individual logo on the right side (jtrac.header.text). If no logo is set the original
- JTrac logo is shown. If the jtrac.edit.item configuration item is set to true people may
- edit their own items while no change is happens (editable item up to the first history entry).
- Admins are always able to change the original item text.
- </para>
-
- </sect1>
- <sect1 id="installation-war">
- <title>Using only the WAR file</title>
- <para>
- 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 <ulink url="http://tomcat.apache.org/">Apache Tomcat</ulink> 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.
- </para>
- <para>
- 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.
- </para>
- </sect1>
- <sect1 id="installation-custom">
- <title>Custom Installation</title>
- <para>
- 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.
- </para>
- <sect2 id="installation-custom-initprops">
- <title>Edit the "jtrac-init.properties" file</title>
- <para>
- 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".
- </para>
- </sect2>
- <sect2 id="installation-custom-servletparams">
- <title>Set a Servlet context parameter</title>
- <para>
- For example you can specify the jtrac.home using the Tomcat administration console or as
- follows using a <Context> parameter.
- </para>
- <para>
- <programlisting>
- <![CDATA[
-<Context docBase="${catalina.home}/jtrac/jtrac.war">
- <Parameter name="jtrac.home" value="C:/data/jtrac_home"/>
-</Context> ]]>
- </programlisting>
- </para>
- </sect2>
- <sect2 id="installation-custom-systemparams">
- <title>Set a System / JVM parameter</title>
- <para>
- 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 <ulink url="http://tomcat.apache.org/">Apache Tomcat</ulink> 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:
- </para>
- <para>
- <programlisting>
-
-set JAVA_OPTS=-Djtrac.home=C:/data/jtrac_home -Dfile.encoding=UTF-8
- </programlisting>
- </para>
- <para>
- 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".
- </para>
- </sect2>
- </sect1>
- <sect1 id="installation-database">
- <title>Using a different database such as MySQL</title>
- <para>
- 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:
- </para>
- <para>
- <programlisting>
-
-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
- </programlisting>
- </para>
- <para>
- 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 <ulink url="http://www.hibernate.org/hib_docs/reference/en/html/session-configuration.html#configuration-optional-dialects">this list</ulink>.
- 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.
- </para>
- <para>
- 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!
- </para>
- <para>
- 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.
- </para>
- <para>
- 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.
- <programlisting>
-
-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
- </programlisting>
- </para>
- <para>
- For MySQL, do not use the "autoReconnect=true" parameter in the MySQL URL, this is
- <ulink url="http://dev.mysql.com/doc/connector/j/en/connector-j-usagenotes-j2ee.html#connector-j-usagenotes-tomcat">not recommended</ulink>
- by the MySQL team. The <ulink url="http://jakarta.apache.org/commons/dbcp/">Apache DBCP</ulink>
- connection pool used internally by JTrac is configured to refresh stale database connections.
- </para>
- <para>
- 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.
- </para>
- <para>
- 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:
- <programlisting>
-
-create database jtrac charset utf8;
- </programlisting>
- 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:
- <programlisting>
-
-database.url=jdbc:mysql://localhost/jtrac?useEncoding=true&characterEncoding=utf8
- </programlisting>
- </para>
- <para>
- 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.
- </para>
- </sect1>
- <sect1 id="installation-jndi-datasource">
- <title>Using a JNDI Datasource</title>
- <para>
- 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.
- </para>
- </sect1>
- <sect1 id="installation-ldap">
- <title>Configuring LDAP Authentication</title>
- <para>
- 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.
- </para>
- <para>
- <programlisting>
-
-ldap.url=ldap://myldaphost
-ldap.searchBase=DC=foo,DC=bar,DC=org
- </programlisting>
- </para>
- <para>
- The following additional entry is recommended if you are using Active Directory. This switches on an
- LDAP optimization that is specific to Active Directory.
- </para>
- <para>
- <programlisting>
-
-ldap.activeDirectoryDomain=MYDOMAIN
- </programlisting>
- </para>
- <para>
- 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.
- </para>
- </sect1>
- <sect1 id="installation-cas">
- <title>Integrating with CAS for Single Sign On</title>
- <para>
- In order to integrate JTrac with <ulink url="http://www.ja-sig.org/products/cas/">CAS</ulink>
- 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.
- </para>
- <sect2 id="installation-cas-webxml">
- <title>Changes to web.xml</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Change "applicationContext-acegi.xml" to "applicationContext-acegi-cas.xml".
- This appears towards the start of the file in the 'contextConfigLocation' context-param.
- </para>
- </listitem>
- <listitem>
- <para>
- Uncomment the filter and filter-mapping XML for the 'acegi' FilterToBeanProxy
- </para>
- </listitem>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect2>
- <sect2 id="installation-cas-appcontext">
- <title>Changes to applicationContext-acegi-cas.xml</title>
- <para>
- In the XML corresponding to bean id "casProxyTicketValidator" - edit the following
- property values to suit your environment:
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- casValidate
- </para>
- </listitem>
- <listitem>
- <para>
- proxyCallbackUrl
- </para>
- </listitem>
- <listitem>
- <para>
- trustStore
- </para>
- </listitem>
- <listitem>
- <para>
- loginUrl
- </para>
- </listitem>
- <listitem>
- <para>
- logoutUrl
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- For more details and troubleshooting, you can refer to the
- <ulink url="http://www.acegisecurity.org/guide/springsecurity.html#cas-client">Acegi documentation on CAS integration</ulink>.
- </para>
- </sect2>
- </sect1>
- <sect1 id="installation-windowsservice">
- <title>Installing as a Windows Service</title>
- <para>
- 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.
- </para>
- <para>
- If you choose to use the bundled <ulink url="http://jetty.mortbay.org/">Jetty</ulink> 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...
[truncated message content] |
