Developer Environment Setup

The following is a guide to get the MetPetDB development environment set up on your local machine.

First you must install the necessary tools and database software:

Tools and Resources

IMPORTANT: Avoid spaces like the plague. Do not place any of these tools in a file path that has spaces. So for Windows, installing to My Documents or Program Files is bad. While some of these may work fine under these circumstances, it will save a lot of grief if you just avoid it.

PostgreSQL (download: Windows | Linux | Mac -- Version 8.1.x or 8.2.x seem to work)
The SQL database behind MetPetDB is PostgreSQL. Install the server according to the documented guidelines. However, do not check the box to install PostGIS as that will be done separately. Be sure to keep the password and username you provide in a readily accessible location as you will need this data again at a later time. Throughout the installation, use the default settings.

PostGIS (download: Windows | Linux | Mac)
To enable spatial operators (for geopositioning) MetPetDB uses the PostGIS database extension. The PostGIS installation procedure is fairly well documented in the PostGIS documentation itself . During the installation process, you will be given the chance to create a database, but you don’t have to worry about this stuff. We’ve got that covered, so just hang tight!

Mac users: PostGIS requires a few frameworks to be installed BEFORE you install PostGIS. They are packaged in disk images and are currently stored in the repository. Download and install them in this order: PROJ, GEOS, GDAL.

Java Development Kit (JDK) (download Note: already included with Mac OS X)
You do not need Java EE SDK, NetBeans, or JRE. A 1.5.x or later JDK is required to compile MetPetDB. A JRE is NOT sufficient for compiliation, as it does not include the Java compiler. To be sure you have the JDK, a folder should be created on your system that is named "jdk(Version#)".

Windows users: When you have installed Java Development Kit, return to the Environment Variables screen, then...

  1. Under user variables, change PATH to be the address of the bin in the jdk.
  2. In addition, create a new variable JAVA_HOME as a system variable and give it the address of the jdk folder.
  3. Under Path in System Variables, add %JAVA_HOME%\bin.

Eclipse IDE for Java Developers (download)
Eclipse is the preferred IDE for development of this project. Be sure to install the Subclipse plugin to integrate Subversion into the Eclipse project files. More Eclipse plugins.

Google Web Toolkit (GWT) (download)
The MetPetDB client side components must be translated from Java source code to HTML+JavaScript before they can be utilized by a browser. This translator is built into GWT. Installation of GWT is a simple matter of expanding the binary distribution for your platform into a directory.

Apache Ant (download Optional - included with Eclipse )
The MetPetDB build scripts use Apache Ant. Ant installation is just a matter of decompressing the binary distribution and adding the bin/ subdirectory to your PATH. To do this on a windows machine, right click My Computer and traverse the following. My Computer->Properties->Advanced->Environment Variables. Under System Variables, click Path. Select edit and then add a semi-colon and the address of the ant bin. See this guide for editing the PATH in Mac OS X.

Apache Tomcat (download Optional)
To run the MetPetDB server-side components, Java Servlets are used. To make use of these, Apache Tomcat 5.5.x is needed. Standard Tomcat installation instructions should be followed for your platform. It is usually just a matter of downloading the binary distribution and expanding it to a directory on your drive.

Installation Guide

After installing the tools and resources above, it's time to set up Eclipse.

Eclipse Setup

  • With Eclipse open go to Window->Open Perspective->Other... and select SVN Repository Exploring
  • Right click on the Left Pane (SVN Repository) and go to New->Repository Location
  • Enter URL: svn+ssh://mary-kate.cs.rpi.edu/projects/metpetdb/svn
    • Use your RPI CS account username and password to authenticate
  • Expand the newly create repository location, and also expand the trunk directory
  • Right click on mpdb-client and select Checkout...
  • Keep the default settings and click Finish
  • Repeat steps for mpdb-common and mpdb-server
  • Switch back to the Java perspective (Window->Open Perspective->Other... and select Java (Default))
    • You will see three newly created Projects (mpdb-client, mpdb-common, and mpdb-server) they will all have approximately infinity+1 errors
  • Expand the Project mpdb-common
  • Create a new document in the root of the project named build.properties
  • Add to build.properties the following: 
    gwt_home=[your path to gwt]
postgis=[your path to postgis]
DATABASE=[name you want the database to be]
APPUSER=[name of the user you want for the database]
APPPASS=[password of the above user]

As an example: 

gwt_home=/home/anthony/development/gwt-linux
postgis=/usr/share/postgresql-8.2-postgis
DATABASE=mpdb_watera2
APPUSER=metpetwebtst
APPPASS=
  • Right click on build.xml and select Run As->Ant Build...
  • Under Targets select all-eclipse and click Run
    • This will generate the appropriate .classpath file for each of the projects
  • Right click on each of the projects and select Refresh
    • All of the errors for the projects will magically disappear
  • Navigate to mpdb-server/src
  • Create a file called files.properties
    • This properties file contains the paths to where upload files are stored and it should contain the following: (see files.properties.base): 
      fileUpload.path=/full/path/to/store/uploaded_files/
images.path=/full/path/to/store/uploaded_images/

Next, set up the database.

Database Setup

For this initialization to work properly, you must have the files lwpostgis.sql and spatial_ref_sys.sql in the directory specified by postgis= during Eclipse setup.

  • Start up psql (*NIX users can type the command in the terminal, Windows users can go to Start->Programs->PostgreSql->psql)
  • Enter the password for the account you created when you installed PostgreSQL
  • Change directory to mpdb-server/build/schema, An example of this is 
    \cd C:/workspace/mpdb-server/build/schema
  • Execute \i recreate-database.sql

Troubleshooting for Mac

You may run into some trouble setting up the database if you're on a Mac. Here's what worked for me, but it may not be the best solution:

  • Create a new OS X user named postgres (or whatever you prefer)
  • Open up the Terminal and execute the following to initialize the database:
    Note: you do not have to log in as postgres, just some account with admin privileges. 
    $ sudo mkdir /usr/local/pgsql/data
$ sudo chown postgres /usr/local/pgsql/data
$ su postgres
$ initdb -D /usr/local/pgsql/data
  • Then, if you're still having trouble, try turning off logging: 
    $ emacs /usr/local/pgsql/data/postgresql.conf
change line 
	redirect_stderr = on
to
	redirect_stderr = off
  • Restart your computer

You should be good to go! Just run the project...

Running the Project

  • In Eclipse, Go to Run->Open Run Dialog...
  • Select mpdb-server under Java Application and click Run
  • Select mpdb-client under Java Application and click Run MetPetDB

Source Control

To keep your code up-to-date:

Getting the latest code

  • In Eclipse, right click on the project name.
  • Select Team->Synchronize With Repository.
    • This will bring up the Synchronize perspective.
  • On this page, right click the project name and select Synchronize.
    • This will show you the changes that have occurred in the source code, it will not update the code nor commit any of your changes. You need to choose the Update... option to do that.

Committing the Code

  • In Eclipse, right click on the project name. Select Team->Commit.
  • This will bring up a view with check boxes next to the files you have modified.
  • Place a comment in the top box describing the changes you made.
  • Click OK to commit the changes.