Overview

This document is a guide for setting up a Linux workstation for JGATMS development. Some of the steps recommended in this guide are not suitable for production environments for security reasons. Please use the documentation for your database and application server provider for more information on secure deployments.

For advanced users, the Quick Start section should be enough information to get you set up. For others, we've provided Detailed Instructions. The goal with the detailed instructions was to make it possible to get up and running without reading reams of documentation from dozens of packages. This guide should be sufficient for Linux newbies and experienced developers alike.

Quick Start

These Quick Start instructions apply to experienced developers who know how to do basic things like install the JDK, Maven, etc. Detailed instructions are found below for those who need them.

  1. Install JDK 1.4.2
  2. Install the latest Maven Release
  3. Setup the JGATMS Development Tree

    First create a directory to house the JGATMS development tree, for example: $HOME/develop/jgatms. Then checkout the JGATMS CVS repository using one of the commands described in the detailed instructions below. After checking out the codebase you should have a "jgatms-core" directory under the directory you created.

  4. Download unavailable dependencies.

    Due to Sun's distribution restrictions the Maven repository cannot keep copies of the Java APIs we use. Therefore you must download them directly from Sun and put them in a place where Maven will be able to find them.

    Create a "lib" directory under "jgatms-core" and put these jars there. If using the fscontext provider make sure the context is created. On my machine I created a directory called "stuff" and the jndi.properties file under jgatms-core/conf/test points to it. See the detailed instructions for more information.

    Here are the Java Packages you will need.

    • JTA
    • JNDI (included with the JDK)
    • ProviderUtil
    • File System Context (or another JNDI service provider)
  5. Set up the application server. We recommend Tomcat, but any J2EE-compatible application server that provides a Servlet container should be sufficient.
  6. Set up the database.

    By default JGATMS uses a PostgreSQL database. In theory, you should be able to use any database that works with Hibernate, but, to date, no others have been tested.

    Once you have set up and initialized your database server create a database called "jgatms." There are two scripts under jgatms-core/src/sql that should be run in order: create.sql and insert.sql. These scripts will build the database and load test data into it.

  7. Execute Maven build. Typing 'maven dist' in the jgatms-core directory should do the trick.

Detailed Instructions

Install the Java Development Kit 1.4.2

Point your browser to http://java.sun.com . Click on J2SE -> J2SE Downloads -> J2SE 1.4.2. Scroll down to the table that says "Download J2SE v 1.4.2_02" and look for "Linux RPM in self-extracting file" and click on the "DOWNLOAD" link under SDK (not JRE).

Once you click through the License Agreement you will get to a page to download a 34MB file called j2sdk-1_4_2_02-linux-i586-rpm.bin. Download that to your computer. Open a shell prompt to the directory where you downloaded the file above su to root and type the following: 

chmod +x *.bin
./j2sdk-1_4_2_02-linux-i586-rpm.bin
rpm -i j2sdk-1_4_2_02-linux-i586-rpm

Type "exit" or Ctrl+D to exit the root login. Now, open the $HOME/.bash_profile file and add the following: 

PATH=$PATH:/usr/java/j2sdk1.4.2/bin
JAVA_HOME=/usr/java/j2sdk1.4.2

export JAVA_HOME

Log out and log back in to reexecute your profile script. Then type "java -version" and you should see 1.4.2 as the Java version. If so, Java install was successful.

Install the Latest Maven Release

Go to http://maven.apache.org and install the latest release of Maven according to the instructions. You will download and unpack the tar.gz file, then edit .bash_profile again and add a MAVEN_HOME variable that points to the directory where you unpacked Maven. Also add the Maven bin directory to your path. Log out and log back in and type: 

install_repo.sh $HOME/.maven/repository

Setup Your Sourceforge CVS Account (JGATMS committers only)

This section is for JGATMS committers only. All others can skip to the next section.

Log onto http://sourceforge.net and click on "SIte Docs." Scroll down and find "F2. Introduction to SourceForge.net Project CVS Services for Developers." You should read this document completely, but pay particular attention to and follow the instructions titled "Developer CVS Repository Access: Creating your home directory." Also read the document "F1. Introduction to CVS and SourceForge.net (SF.net) Project CVS Services" to familiarize yourself with CVS.

Setup the JGATMS Development Tree

Create a direc tory called jgatms and change into it. Type one of the following depending on whether you want to log into cvs as a user or developer. For these purposes it doesn't matter at all which you are, but the developer settings are only for JGATMS committers.

As a user, type: 

cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/jgatms login

Hit enter at password prompt. Then type: 

cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/jgatms checkout jgatms-core

As a developer type: 

CVS_RSH=ssh
cvs -d:ext:[username]@cvs.sf.net:/cvsroot/jgatms checkout jgatms-core

Where [username ] is your sourceforge user name. Type your password when asked.

After typing one of these sets of commands you should see some text scroll across as you download the source code.

Your jgatms directory should now have the following files and subdirectories: 

jgatms-core/config
jgatms-core/gen
jgatms-core/LICENSE.txt
jgatms-core/project.properties
jgatms-core/project.xml
jgatms-core/src
jgatms-core/web

Download unavailable dependencies.

JGATMS either directly or indirectly depends on several Java and J2EE APIs. Sun's redistribution restrictions make it impossible for Maven to host these APIs in their repositories. So you must download these packages manually and place them in a place where Maven can find them. To do this create a "lib" directory under jgatms-core. Then place the JAR files listed below in the "lib" directory. The project.properties file is already configured to find them there.

  • JTA - The Java Transaction API.

    Go to http://java.sun.com/jta . Scroll down to "Java Transaction API Specification 1.0.1B" and click on the "Continue" button beside "Class Files." You should eventually get to a jta.jar file which should be placed in the lib directory.

  • JNDI - The Java Naming and Dir ectory Interface (included with the JDK)

    In its simplest form, JNDI provides a Context in which developers can store named items they intend to use in their applications. Application servers provide a JNDI implementation, but we need an independent implementation to do testing outside of application servers.

    There are basically two parts of the JNDI package. The API is provided with the JDK. You must download and install a Service Provider. Each Service Provider will include at least two jar files: providerutil.jar and another Jar that contains the implementation classes. Both of these Jar files must be included in the lib directory.

  • File System Context (or another JNDI service provider)

    The least obtrusive JNDI service provider is the File System Provider. To get it go to http://java.sun.com/jndi and scroll down to a select box titled "Download JNDI 1.2.1 & More." In the drop-down select "File System Service Provider" or another one that suits your needs. These instructions explain how to set up the file system provider. You will have to follow the provider's instructions if you choos another one.

    The File System Service Provider stores the JNDI context on the file system of your computer. After you download it, you will need to place the fscontext.jar file in the lib directory under jgatms-core. You will then need to create a directory somewhere for it to store its context in. Mine is $HOME/develop/jgatms/stuff. Finally, edit the jgams-core/conf/test/jndi.properties file and make sure it has a line such as the following: java.naming.provider.url=file:///home/greddin/develop/jgatms/stuff that points to the directory you created.

Set up the application server.

The JGATMS team recommends Tomcat, but any J2EE-compatible application serve r should work. These instructions explain how to set up Tomcat.

Point your browser to http://jakarta.apache.org/tomcat . Click on Download Binaries. Scroll down until you see the link "4.1.29tar.gz" Download that file. It will create a file called "jakarta-tomcat-4.1.29 tar.gz". In the directory where you downloaded it type "tar -xzf jakarta-tomcat-4.1.29 tar.gz." It should create a directory called jakarta-tomcat-4.1.29. Change to the jakarta-tomcat-4.1.29/bin directory and type the following: 

./startup.sh
tail -f ../logs/catalina.out

Assuming everything is found, it will boot up the Tomcat server. When text stops scrolling open up a browser and point it to http://localhost:8080 You should see the Tomcat home page.If so, Tomcat install was successful.

Set up the database.

There is nothing that requires the use of PosgreSQL as the database backend. Any DBMS that is compatible with Hibernate 1.2 will work. MySql is another good open-source choice, however, I experienced some problems using it on Windows that have been so far unable to debug. I'm using PostgreSQL 7.3. These instructions will not explain how to install PostgreSQL, but how to set it up for use with JGATMS. For more information see http://www.postgresql.org.

First of all, check that PostgreSQL is installed. Typing "rpm -qa | grep postgresql" should do the trick on RedHat. If it's not installed see the PostgreSQL website for installation instructions.

The following steps will need to be done as root.

Initialize the database by typing "/sbin/service postgresql start".

Edit the file /var/lib/pgsql/data/postgresql.conf and make sure there is a line "tcpip_socket = true" that is not commented out.

Now edit /var/lib/pgsql/data/pg_hba.conf and make sure the following two lines are present and uncommented: 

local  all      all             ident   sameuser
host    all         all         127.0.0.1         255.255.255.255   trust

The previous two steps ensure that PostgreSQL listens to TCP/IP connections.

Now we need to set up users and the database. Type "/sbin/service restart postgresql" to restart the database server. Then switch to user "postgres." This user is created by the PostgreSQL initialization As "postgres" type "createuser [username ] " and replace [username ] with the user name you normally log on as. Allow the new user to create users and databases when asked.

Now exit the postgres and root logins and return to your normal login and type "createdb jgatms" to create the JGATMS database.

There are two scripts you must run to get the database setup. In the jgatms-core directory, type the following: 

psql -f src/sql/create.sql
psql -f src/sql/insert.sql

This will create and populate the JGATMS database. You will see a lot of errors the first time you run the scripts, but everything should work fine.

Execute Maven build.

In the jgatms-core directory type "maven dist". If you're on a dialup connection, go eat dinner. Maven will download several packages and build. At the end you will see a message that says "BUILD SUCCESSFUL". If you see "BUILD FAILED" then either you have something misconfigured or these instructions are wrong. Please send an email to the JGATMS Developers list for help. After all is said and done you will have a "target" directory with everything built in it.

At this time, Maven does not create a deployable web application, mainly because there is nothing to deploy. In the very near future there will be some web artifacts to build and we'll configure Maven to create a WAR file as part of its build process.