HOME - Habitat Open Management Engine
Preface
HOME is a web-based application to aid Habitat For Humanity Affiliates in
tracking information pertaining to local Habitat homeowners. It will
track the mortgages of each homeowner, and will also track other
important homeowner information. It is our hope that such a database
application will relieve a Habitat Affiliate's office staff of much of
the tedious labor associated with tracking homeowner and mortgage
information. The database application will also improve the quality,
quantity, and usability of homeowner information.
Each Habitat for Humanity affiliate adds to Habitat For Humanity's
primary mission of ridding the world of substandard housing by working
towards ridding the city Harrisburg of substandard housing. It is the
belief of Habitat for Humanity that everyone in the world deserves a
decent place to live. By utilizing the generosity of volunteers, Habitat
for Humanity is able to build houses and sell them with affordable,
interest-free mortgages to people in need.
PLEASE NOTE: This is a development release only. In it's current state,
HOME should not be used in a production level environment.
HOME is licensed under the Lesser Gnu Public License (LGPL). A copy of
the LGPL can be found in the LGPL.txt file.
It is highly recommended that you read this entire document before working
with HOME. There are some very important pieces of information that you
should not ignore.
Table of Contents
Preface
Table of Contents
I. Requirements
II. Included Tools and Libraries
III. Configuring Tomcat
IV. Configuring Postgresql
V. Setting Up the Database
VI. Compiling
VII. Installing From Binary Distrobution
VIII. Running HOME
IX. System OverviewX. The HOME Team
XI. Project Wiki
XII. Release History
I. Requirements
Sun's Java Standard Edition SDK and JVM Version 1.4.1 or higher
You can download the SDK at
http://java.sun.com - Jakarta Tomcat 4x or higher
You can download and find instructions on how to install Tomcat at
- Postgresql 7.3.x or higher
You can download and find instruction on how to install Postgresql at
- Apache Ant
You can download and find instruction on how to install Ant at
II. Included Tools and Libraries
Several open source tools are included with this release of HOME. HOME
uses these tools at both compile time, and run time.
Beangen - A Java program which generates JavaBeans when given an
appropriately formatted XML file.
Beangen has been been released as open source under the LGPL. A copy of
the LGPL can be found in the same directory as this README file.Beangen is able to query a database, and generate beans based on meta
table data from the database. HOME uses this feature for many of the
JavaBeans. Beangen runs at compile time. No configuring of Beangen
should be necessary, Beangen should run right out of the box.
JasperReports - A Java based library which generates reports using data
from a database.
This product includes software developed by Teodor Danciu
(JasperReports can export reports in multiple formats, including PDF. HOME
uses JasperReports to generate all reports (including invoices) that the
user needs to print out. By using ?JasperReports, we avoid using HTML for
our reports in which the appearance greatly depends on the web browser.JapserReports was written by Teodor Danciu, and is licensed both under
the LGPL, and the ?JapserReports Software License. Both licenses can be
found in the webapp root directory of the source, (which should be the
same directory that this readme is in) in LGPL.txt and
JasperReportsLicence.txt.The JasperReports main website can be found at
III. Configuring Tomcat
In order for the report generation features of HOME to work properly, A
small Tomcat configuration change is required. Please note that this only
required for Non-Windows based environments. Under windows, this
configuration step is optional.
Some interesting issues arise because ?JasperReports utilizes the java.awt
package. Under Unix environments, the default implementation of java.awt
uses native function calls to an X11 environment. Of course if X11 is
not running, the JVM cannot properly run the java.awt packages, and will
through a runtime exception. We also have had problems with getting the
JVM to connect to the X11 server when running Tomcat. The solution to
this problems is to tell the JVM to use a pure Java, X11 independent
implementation of the java.awt classes. This is much easier to do with
Sun's SDK 1.4.1, which is the recommended SDK to build and run HOME
under, has native support for "headless" awt apps.
Assuming that you have the Sun SDK 1.4.1 installed, here is how to
configure Tomcat so that the JVM uses the pure Java implementation of
awt:
In the $TOMCAT_HOME/conf directory, open the tomcat4.conf file for
editing and add the following line:
JAVA_OPTS="-Djava.awt.headless=true"
If JAVA_OPTS is already defined, then just add " -
Djava.awt.headless=true" to the existing Java options.
Other than the above modification, no other Tomcat configurations should
be necessary.
Again, if you are using Windows, this modification is completely
optional, and can be safely ignored.
IV. Configuring Postgresql
In order to use HOME, or even log into home, you will first need to
properly configure Postgresql. If you have done a fresh install of
Postgresql, it is actually easier to set up the home database before
configuring Postgresql itself, so you may want to skip down to Setting Up
the Database first.
Once you have Postgresql installed, you will need to configure it to
properly work with HOME. You will find all relevant config files in the
postgres data directory.
(1) Change the pg_hba.conf file so that it allows any client to connect
to the database using any database username for all local hosts (make
sure you specify this for both the unix socket and the tcp/ip flavors).
These settings will allow HOME to connect, but not anyone trying to
connect from a different machine. We also recommend that you turn on
password authentication.Example:
local all all password host all all 127.0.0.1 255.255.255.255 password
(2) In the postgresql.conf file, set the tcpip_socket value to true
(by default it is commented out and set to false). JDBC drivers can only
connect by tcp/ip, so this is a necessary step.
V. Setting Up The Database
Before HOME is all that useful, you will need to set up the database.
This section assumes that you are familiar with Postgresql. If you are
not, you should read the documentation provided at
http://www.postgresql.org.
(1) Create the database user. The database user is the user that HOME
will use to access the database in Postgresql. The username and password
are stored in the home.xml file in the base directory. Actually, since we
use Tomcat's Realm mechanism and Tomcat's ?ResourceParm mechanism to
utilize database connection pooling, the username and password is stored
in the home.xml file twice.So as a word of caution, if you change the database user name and
password, make sure you change it in both places.(2) After creating the user, log into Postgresql using the user name
of the user that you just created, and create a database with the name
"home". Then connect to that database, and load the schema. Don't be
alarmed by all the warning messages, those are normal. The schema for the
HOME database can be found in the /HOME/db/schema.sql file.(3) Lastly, you need to put in some entries into the users and
userroles tables so that you will be to log into the actual web
application. Make sure that for the user you create, it has the roll
"habitat".(4) Some sample data is also included with this release. You may want to
load the sample data so that you may start testing HOME without having to
make up, and enter your own data. The sample data is stored in a file
called sampledata.sql, and can be found in the /HOME/db directory.
VI. Compiling
Before you can compile HOME, you will need a build script. Two example
build scripts (build.sh.example, and build.bat.example) are provided with
this release. build.sh.example is for Unix-like environments, and
build.bat.example is for Windows environments. Documentation in using
each build script are in the example build scripts themselves.
The actual source for the web application can be found in the
./HOME/webapp directory. It is in the webapp directory that you will find
the build.xml file and the example build scripts.
Also before you can compile, you will need to specify the TOMACAT_HOME,
environment variable, which should be set to the directory that Tomcat
resides in, and the CLASSPATH environment variable.
IMPORTANT: Make sure that your jdbc driver for Postgresql is in your
CLASSPATH and also in the TOMCAT_HOME/commons/lib directory! If it is
not in your CLASSPATH, then Beangen will not be able to generate beans
from the database, and if it is not in the TOMCAT_HOME/common/libs
directory, HOME will not be able to find the jdbc driver ether.
IMPORTANT: You will not be able to compile the ?JasperReports files unless
you have the Ant optional tasks installed. Consult the Ant documentation
on what those are, and how to install them.
Once you have satisfied the above requirements, you should be able to
compile HOME by simply just running the build script in the same
directory as the build.xml file.
When you compile, HOME will be installed in TOMCAT_HOME/webapps/home
VII. Installing From Binary
If you have downloaded HOME as a precompiled binary, then you should
still follow the configuration instructions above. You do not, however,
have to worry about the compiling section.
Please follow these steps to install HOME from the binary distrobution
(1) Copy the home.war file into the TOMCAT_HOME/webapps directory.
Depending on your Tomcat configuration, Tomcat may or may not
automatically expand the war file, and deploy it. If it does
not, you will need to restart Tomcat.(2) AFTER Tomcat has succesfully expanded the home.war file (there should
be a directory in TOMACT_HOME/webapps called "home"), copy the home.xml
file to the TOMCAT_HOME/webapps directory.
(3) Restart Tomcat once more.
That's all there is to it!
VIII. Running HOME
In order to run home, first make sure that you have satisfied everything
from above (yeah, all that great fun stuff like configuring Tomcat and
setting up the database). Also make sure that you have compiled, and
installed HOME.
After that, just point your browser to http://localhost:8080/home, log
in, and you are good to go! (Hopefully).
You can also wrap Tomcat in a web server such as Apache, thus allowing
you to access home on port 80. For more information on how to wrap Tomcat
with Apache or any other web server, consult the Tomcat documentation.
IX. System Overview
HOME is build upon the Jakarta Struts 1.1 Framework, and conforms to the
Model-View-Controller framework. For more information on Struts, visit
http://jakarta.apache.org/struts/ . If you are familiar with Struts,
then you should find the design fairly straight forward.
If you are not familiar with Struts and MVC philosophy, then you may find
this application difficult to fully understand.
We recommend that you read the paper written by Jonathan and Jim which
discusses the overall design of HOME. You can find this paper on the
Project Wiki.
X. The HOME Team
The core HOME team is comprised of four students at Messiah College near
Harrisburg PA. We are:
Jonathan Corbin
Tom Setliff
Denny Daughterty
Jim Hurne
(Actually Jonathan and Jim have graduated as of May 17th, 2003, but are
still very active in developing HOME).
XI. Project Wiki
From the beginning of this project, we have maintained a Project Wiki
containing all of our project documentation, some of which you may find
useful, and maybe even interesting. Feel free to visit. The Wiki can be
found at http://cs.messiah.edu/habitat .
XII. Release History
2003/04/09 - Version 0.11:
Initial development release.
