Installation Instructions for Taskjitsu
TABLE OF CONTENTS
-----------------
1. Installation Prerequisites
2. Tomcat Notes
3. Installation on Windows XP
4. Installing from RPM packages on RHEL 3 + RHAS
5. Installing from binary distribution
6. Installing on Fedora Core with a JPackage 1.6 build environment
7. A note about GNU Classpath, JavaMail and the Java Activation Framework
8. Installing from Source
1. Installation Prerequisites
-----------------------------
Taskjitsu is a Java Web application that requires a Servlet 2.0-compatible
Web container, such as Apache Tomcat 5.0 .
It also requires the server-based SQL database PostgreSQL
, version 7.2 or higher.
Taskjitsu has been tested on Windows XP, Red Hat Linux 7.3, and
Fedora Core 2. It has been tested versus PostgreSQL 7.2.4, 7.4.2, and 8.0.
It should run on any operating system that can run Tomcat 5+ and
PostgreSQL 7.2+, though.
Before you begin installing Taskjitsu, please ensure that you have
the following software installed:
* Java JDK 1.4.2 +
* Tomcat 5.0
* PostgreSQL
* Java Activation Framework
* JavaMail API
You can find activation.jar in the Java Activation Framework:
http://java.sun.com/products/javabeans/glasgow/jaf.html
You can find mail.jar in the JavaMail API:
http://java.sun.com/products/javamail/
See "7. A note about GNU Classpath, JavaMail and the Java Activation Framework"
below for an alternative to downloading these non-free libraries from Sun.
It should be possible to use another J2EE Web container to run Taskjitsu,
but you will need to configure the deployment environment to provide the
same container-managed resources (the "jdbc/taskjitsu" javax.sql.DataSource
resource and access to javax.mail.session classes) as Tomcat
provides.
Taskjitsu runs well under Tomcat 5.0.28 and 5.0.30.
Tomcat 5.5 could be used provided that the META-INF/context.xml file in the
deployed war was altered to match the new javax.sql.DataSource configuration
syntax as described here:
http://www.crazysquirrel.com/java/connection-pooling.php
2. Tomcat Notes
---------------
If you are running Tomcat 5.0, you will need to copy three files into
the $TOMCAT_HOME/common/lib directory:
* activation.jar
* mail.jar (distributed as "javamail.jar" in JPackage-derived systems)
* your PostgreSQL JDBC driver jar file
The activation.jar file comes from the Java Activation Framework.
The mail.jar file comes from the JavaMail API.
The PostgreSQL jar file comes from your Postgres installation (in RPM-based
systems, it is typically in postgresql-jdbc RPM).
Without these jar files, Taskjitsu will not run.
3. Installation on Windows XP
-----------------------------
Taskjitsu has been tested on Windows XP using PostgreSQL 8.0 and
Tomcat 5.0.30. These instructions should allow you to install
Taskjitsu on Windows XP. They assume that you are going to run
both the application and the database on the same computer.
3.1 Install JDK
---------------
Install a working Java Development Kit, version 1.4.2 or higher.
You can download Sun's JDK from their website:
http://java.sun.com/j2se/index.jsp
3.2 Install PostgreSQL
----------------------
Install PostgreSQL:
http://www.postgresql.org
The PostgreSQL site has an installer for Windows XP; this is the easiest
way to get it installed. Make sure when installing you setup PostgreSQL
to run under a seperate, limited, account and not an account with
administrative privileges.
The PostgreSQL installation program should create the default database
superuser account (the "postgres" account).
3.2.1 Configure PostgreSQL
--------------------------
You will need to make sure that PostgreSQL is listening for TCP
connections, and that PostgreSQL is configured to allow password
authentication from localhost.
Ensure that PostgreSQL listens on TCP/IP sockets by uncommenting, or adding
this setting to the postgresql.conf file:
(C:\Program Files\PostgreSQL\8.0\data\postgresql.conf)
listen_addresses = 'localhost'
You will need to add this line to the pg_hba.conf file to get
PostgreSQL to accept password authentication from localhost:
(C:\Program Files\PostgreSQL\8.0\data\pg_hba.conf)
host all taskjitsu 127.0.0.1/32 255.255.255.255 md5
Restart PostgreSQL after making these changes by going to control panel,
administrative tools, services, then right click on PostgreSQL Database
and choose 'restart'.
You should test that you can connect to PostgreSQL using the postgres database
user over TCP sockets. Open a command prompt (cmd), change to your
C:\Program Files\Postgres\bin directory, and run:
psql -U postgres taskjitsu
Enter the password you choose for the postgres user and you should be able to
connect.
3.3 Install Tomcat
------------------
Install Apache Tomcat 5.0.x (5.0.28 is the most current stable version
as of 2005-06-23).
This is available here:
http://jakarta.apache.org/site/downloads/downloads_tomcat-5.cgi
You should avoid running Tomcat under an admin account, as it only needs
normal user rights to run.
3.3.1 Install required libraries into Tomcat's common code repository
---------------------------------------------------------------------
Taskjitsu requires that Tomcat have a working PostgreSQL driver jar file
installed in its C:\Program Files\Tomcat 5.0\common\lib directory.
You should have a PostgreSQL driver jar in your
C:\Program Files\Postgres\jdbc directory. You could also retrieve a
JDBC driver from the master distribution site for these drivers:
http://jdbc.postgresql.org/
You need to copy the JAR file into Tomcat's common\lib directory, typically:
C:\Program Files\Apache Software Foundation\Tomcat 5.0\common\lib
You will also need to ensure that Tomcat has a working JavaMail
environment. Tomcat has support for JavaMail sessions, but
it does not ship with some critical classes. You have to get
these separately from another source. Sun distributes JavaMail and the
Java Activation Framework as royalty-free binary downloads from
the java.sun.com web site:
http://java.sun.com/products/javabeans/glasgow/jaf.html
http://java.sun.com/products/javamail/
Retrieve the jaf-1_0_2.zip and javamail-1_3_1.zip archives, expand
them, and copy the mail.jar and activation.jar
archives into C:\Program Files\Tomcat 5.0\common\lib directory:
3.3.2 Configure Tomcat
----------------------
Make sure Tomcat is started by going to your control panel, administrative
tools, services, and look at Apache Tomcat at the top of the list.
If it does not say 'Started' next to it right click on it and choose 'Start'.
Test that the Tomcat installation is running by visiting the following
web address in your web browser:
http://localhost:8080/
3.4 Install Taskjitsu
------------------------
Now that Tomcat, PostgreSQL, the JDBC driver, the JavaMail classes, and
the JAF classes are in place, we can install the Taskjitsu WAR file:
Open the taskjitsu-2.0-bin.zip and copy the
taskjitsu-2.0/taskjitsu.war file to your tomcat/webapps
directory.
Tomcat should immediately deploy the Taskjitsu web application.
You can start the setup process by visiting this URL:
http://localhost:8080/taskjitsu/
4. Installing from RPM packages on RHEL 3 + RHAS
------------------------------------------------
The easiest way to get Taskjitsu running reliably is under Red Hat
Enterprise Linux 3, in conjunction with the Red Hat Application Server.
This platform provides a JVM, Tomcat 5, PostgreSQL, and all the Java
libraries needed to support an easy installation.
Install Tomcat 5 according to the instructions given in the RHAS
documentation.
Install the taskjitsu and pkr-mvc RPMs, making sure to include the
taskjitsu-tomcat5 RPM.
If PostgreSQL is not started (do a "/sbin/service rhdb status" command
to check), start it with "/sbin/service rhdb start".
Configure PostgreSQL to accept TCP connections and md5 authentication
over localhost sockets, and set a password for the postgres user.
To do this, add this line to /var/lib/pgsql/data/pg_hba.conf:
host all all 127.0.0.1 255.255.255.255 md5
You will also need to tell PostgreSQL to listen on TCP sockets by adding
this line to /var/lib/pgsql/data/postgresql.conf:
tcpip_socket = true
Restart PostgreSQL after you make those changes:
/sbin/service rhdb restart
Then, set the postgres user's database password:
-----BEGIN EXAMPLE-----
$ su -
Password:
# su - postgres
$ psql template1
Welcome to psql 7.3.10-RH, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
template1=# alter user postgres encrypted password 'example-password';
ALTER USER
template1-# \q
-----END EXAMPLE-----
Tweak the firewall to accept connections coming into port 8080.
Then, run the Taskjitsu setup process by connecing over the web:
http://localhost:8080/taskjitsu/
5. Any UNIX / Linux environment with a working 1.4 JDK
------------------------------------------------------
These instructions should work on any UNIX or Linux environment.
They assume that you are going to run both the application and
the database on the same computer.
For the sake of example, the following instructions will use
Red Hat Enterprise Linux 4 ES (RHEL 4 ES) as a typical environment.
5.1 Install JDK
---------------
Install a working Java Development Kit, version 1.4.2 or higher.
This may be available from your vendor.
(On RHEL 4 ES, follow these steps to install the JDK:)
# First, in your Red Hat Network setup, enable the "Extras" channel
# Then, run this command:
up2date java-1.4.2-ibm
5.2 Install PostgreSQL
----------------------
Install PostgreSQL. Your operating system may have a PostgreSQL server
package available; this is the easiest way to get it installed. If not,
you can download the latest version from .
(On RHEL 4 ES, follow these steps to install PostgreSQL:)
up2date postgresql-server postgresql-jdbc
5.2.1 Configure PostgreSQL
--------------------------
You will need to make sure that PostgreSQL is listening for TCP
connections, and that PostgreSQL is configured to allow password
authentication from localhost.
Ensure that PostgreSQL listens on TCP/IP sockets by adding this setting
to the postgresql.conf file:
(/var/lib/pgsql/data/postgresql.conf on RHEL 4 ES)
tcpip_socket = true
You will need to add this line to the pg_hba.conf file to get
PostgreSQL to accept password authentication from localhost:
(/var/lib/pgsql/data/pg_hba.conf on RHEL 4 ES)
host all all 127.0.0.1 255.255.255.255 md5
Restart PostgreSQL after making these changes.
(/sbin/service postgresql restart on RHEL 4 ES)
By default, the PostgreSQL database superuser 'postgres' has no password
set. To set up Taskjitsu, we need to have a PostgreSQL user available
who has permission to set up databases and users. For convenience sake, you
should set a password for the "postgres" user (use something other
than "example-password", please):
-----BEGIN EXAMPLE-----
$ su -
Password:
# su - postgres
$ psql template1
Welcome to psql 7.4.8, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
template1=# alter user postgres encrypted password 'example-password';
ALTER USER
template1-# \q
-----END EXAMPLE-----
You should test that you can connect to PostgreSQL using the
"postgres" database user over TCP sockets:
-----BEGIN EXAMPLE-----
$ psql -h localhost -U postgres template1
Welcome to psql 7.4.8, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help on internal slash commands
\g or terminate with semicolon to execute query
\q to quit
template1=# \q
-----END EXAMPLE-----
5.3 Install Tomcat
------------------
Install Apache Tomcat 5.0.x (5.0.28 is the most current stable version
as of 2005-06-23).
This is available here:
http://jakarta.apache.org/site/downloads/downloads_tomcat-5.cgi
Typically, you would install Tomcat under /usr/local, for example
/usr/local/jakarta-tomcat-5.0.28.
You should avoid running Tomcat as root, as it only needs normal user
rights to run. This series of commands will expand the archive and create
a 'tomcat' user that will own the files and run the program:
-----BEGIN EXAMPLE-----
# This assumes that the Tomcat tar file is in /tmp
su
cd /usr/local
tar xfz /tmp/jakarta-tomcat-5.0.28.tar.gz
# Add the Tomcat user
groupadd -r tomcat
useradd -g tomcat -r -d /usr/local/jakarta-tomcat-5.0.28 -c 'Tomcat' tomcat
chown tomcat.tomcat -R jakarta-tomcat-5.0.28
-----END EXAMPLE-----
5.3.1 Install required libraries into Tomcat's common code repository
---------------------------------------------------------------------
Taskjitsu requires that Tomcat have a working PostgreSQL driver jar file
installed in its $TOMCAT_HOME/common/lib directory. Most operating systems
that distribute PostgreSQL also distribute its JDBC drivers, typically in
a postgresql-jdbc package. You could also retrieve a JDBC driver from the
master distribution site for these drivers .
You need to copy the JAR file into the common/lib directory.
(For example, on RHEL 4 ES:)
cd /usr/local/jakarta-tomcat-5.0.28/common/lib
cp /usr/share/java/pg74.215.jdbc3.jar postgresql.jar
You will also need to ensure that Tomcat has a working JavaMail
environment. Tomcat has support for JavaMail sessions, but
it does not ship with some critical classes. You have to get
these separately from another source. Sun distributes JavaMail and the
Java Activation Framework as royalty-free binary downloads from
the java.sun.com web site:
http://java.sun.com/products/javabeans/glasgow/jaf.html
http://java.sun.com/products/javamail/
Retrieve the jaf-1_0_2.zip and javamail-1_3_1.zip archives, expand
them, and copy the mail.jar and activation.jar
archives into Tomcat's common/lib directory:
# This assumes you have put the zip files in the /tmp directory
cd /tmp
unzip jaf-1_0_2.zip
unzip javamail-1_3_1.zip
cp javamail-1.3.1/mail.jar /usr/local/jakarta-tomcat-5.0.28/common/lib
cp jaf-1.0.2/activation.jar /usr/local/jakarta-tomcat-5.0.28/common/lib
5.3.2 Configure Tomcat
----------------------
Before Tomcat will run, you usually need to set the JAVA_HOME environment
variable. For example, on Red Hat Enterprise Linux 4 with the Red Hat Extras
IBM JDK:
JAVA_HOME=/usr/lib/jvm/java-1.4.2-ibm-1.4.2.1
export JAVA_HOME
Now that all these files are in place, Tomcat needs to be started (or
restarted if it was already running).
(For example, on RHEL 4 ES:)
su tomcat /usr/local/jakarta-tomcat-5.0.28/bin/startup.sh
Test that the Tomcat installation is running by visiting:
http://localhost:8080/
You may need to configure your local firewall to allow connections to
Tomcat's port 8080 from the outside. For example, on RHEL 4, you can add
this line to /etc/sysconfig/iptables after the line with '--dport 80':
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8080 -j ACCEPT
(execute "/sbin/service iptables condrestart" to activate this)
5.4 Install Taskjitsu
------------------------
Now that Tomcat, PostgreSQL, the JDBC driver, the JavaMail classes, and
the JAF classes are in place, we can install the Taskjitsu WAR file:
tar xfz taskjitsu-2.0-bin.tar.gz
su
cp taskjitsu-2.0/taskjitsu.war /usr/local/jakarta-tomcat-5.0.28/webapps/
Tomcat should immediately deploy the Taskjitsu web application.
You can start the setup process by visiting this URL:
http://localhost:8080/taskjitsu/setup
6. Installing on Fedora Core with a JPackage 1.6 build environment
------------------------------------------------------------------
The easiest way to get Taskjitsu to build is probably to work on
Fedora Core (version 3 or higher), using the JPackage 1.6 set of Java
packages. See and
for more information on these projects.
You need tomcat5, but to get that, you need a few non-free dependencies
(jta, and either java-1.4.2-sun-compat or one of the other non-free
java development packages). If you install Sun's java RPM, you can install
the java-1.4.2-sun-compat package to satisfy most of the dependencies.
That might be easiest. Even after that, you'll still need to build a binary
RPM of jta. That requires downloading a package from Sun.
If you choose to build another one of the other java-1.4.x or java-1.5.x
non-free JVMs, that could work too, you'll just have to follow JPackage's
installation instructions.
6.1 Fedora Core 4 / gij Java environment setup
---------------------------------------------
On Fedora Core 4, Taskjitsu comes tantalizingly close to running
within the free gij Java stack.
However, a critical bug in the version of libgcj that shipped with
Fedora Core 4 will prevent Taskjitsu from installing. you must ensure
that you have an updated gcc4 and libgcj of at least version 4.0.0-10. This
should be available from the Fedora Core 4 updates channel by the end
of July, 2005. You can update these by issuing either of these commands:
up2date libgcj
yum update libgcj
There are other bugs that currently prevent Taskjitsu from working
properly on Fedora Core 4 (bugs #3133 and 3134), mostly having to do with
date and number formatting:
https://www.pkrinternet.com/taskjitsu/task/3133
https://www.pkrinternet.com/taskjitsu/task/3134
7. A note about GNU Classpath, JavaMail and the Java Activation Framework
----------------------------------------------------------------------
The GNU Classpath project is working to provide a working JavaMail
implementation, but currently you have to have GNU Classpath installed to
get one of the prerequisite libraries (inetlib.jar). The JavaMail download
provided does not contain inetlib.jar, nor does the Classpath project
currently provide this jar in binary form. Hopefully this will change in
the future. If you want to avoid using Sun JavaMail and Java Activation
Framework, you can investigate the current state of GNU JavaMail here:
http://www.gnu.org/software/classpathx/javamail/javamail.html
8. Installing from Source
--------------------------
First make sure you have the following installed per the above binary
installation instructions for your operating system:
* Java JDK 1.4.2 +
* Tomcat 5.0
* PostgreSQL
* Java Activation Framework
* JavaMail API
You will also need ant installed. You can find it, and instructions for
installing it, at http://ant.apache.org/. Using the JPackage RPMs, or the Red
Hat Application Server will, make satisfying the dependencies much easier for
systems where that is an option.
Then create a .ant-taskjitsu.properties file in your user home directory that
contains the following values (with appropriate values filled in):
jdbcPassword=
jdbcTestPassword=
tomcatAdminPassword=
postgresqlPassword=
The only critical values right now are jdbcPassword and tomcatAdminPassword.
Decompress both the taskjitsu and mvc files into the same directory, which
we will refer to as "src". Change to the src/mvc directory and type 'ant'
to create the necessary jar.
Then change to the src/taskjitsu directory and type 'ant deploy' to compile
and install taskjitsu!
Tomcat should immediately deploy the Taskjitsu web application.
You can start the setup process by visiting this URL:
http://localhost:8080/taskjitsu/setup
11. Building from SRPMS
-----------------------
You need either a working JPackage 1.6 environment or RHEL 3 ES with RHAS
to build TaskTracker RPMs from the source or from the SRPMS.
For RHEL 3 ES + RHAS:
# Install Tomcat5, its dependencies, and a few other required Java RPMs:
up2date tomcat5 httpunit jtidy jrefactory ant-nodeps
# Install the pkr-mvc RPM
rpm -ivh pkr-mvc-0.8-5.noarch.rpm
# Rebuild Taskjitsu
rpmbuild --rebuild taskjitsu-2.0-8.src.rpm
12. CVS Integration
-------------------
If you are using CVS for version control there are scripts to create
task notes and timesheet entries when you do a "cvs commit"
These instructions only work under a Unix OS.
# Find a directory to put the scripts (referred to as ${dir}
# copy bin/cvs-task-info.pl into ${dir}
# copy bin/cvs-file-list.pl into ${dir}
# copy bin/TaskData.pm into ${dir}
# copy etc/rcs-task-template.txt into ${dir}
# modify ${dir}/cvs-task-info.pl
* Change the first line's -I to point to ${dir}
# modify ${dir}/TaskData.pm
* Change the $dbname to user the correct database
* Change the $dbuser to an acceptable postgres user who has GROUP web
* Change the $dbauth to the user's password
# modify $CVSROOT/CVSROOT/rcsinfo
* Add the line
DEFAULT ${dir}/rcs-task-template.txt
# modify $CVSROOT/CVSROOT/verifymsg
* Add the line
DEFAULT ${dir}/cvs-task-info.pl
# modify $CVSROOT/CVSROOT/commitinfo
* Add the line
DEFAULT ${dir}/cvs-file-list.pl
And then to enter task information on commits add the line
Task #### [status-name] [percentComple%] [hh:mm]
to your cvs comment.