Installation and Configuration Instructions

Prerequisite Software

We'll assume this prerequisite software is already installed and propertly configured. Each comes with its own instructions, which won't be repeated here.

1. Apache (or equivalent) web server.
2. MySQL : Any recent version that supports transactions (InnoDB) will do. Other relational databases may work with minor changes but this has not been tested. Be sure to assign a root password as described in its instructions. Confirm that it is working properly before proceeding.
3. Java : Download a recent version of the Java Software Development Kit (SDK). Avoid the Java Runtime Environment version (JRE) which is significantly smaller but only capable of running Java, not compiling it.
4. Jetty or Tomcat : Jetty is smaller and faster. Either will do.

You will need these installed on the private computer you'll use to test your work privately and also on the public server you'll copy your work to so others can see it. I'll refer to the first machine as your development or private machine and the other as your deployment or public machine.

The JWAA Distribution Directory Structure

Unpack the distribution archive in your web server's document root directory. If this is /var/www/html, you'd type:

cd /var/www/html
	tar zxf path/to/jwaa.tgz

This will create a new directory, /var/www/html/jwaa, that will be called the installation directory or simply jwaa for brevity. This directory contains:

root, root/jwaa

The subdirectories of the jwaa/root directory define each JWAA application. JWAA is intially distributed with one such subdirectory, jwaa/root/jwaa. This defines the pages you're reading now as three XML files. application.xml defines the application as a whole, outerPages.xml defines the external pages (the pages that are accessible without logging in) and innerPages.xml defines the inner pages (the demo application which requires logging in via the Demo link at the top right of each page.).

The root directory can be moved if you want by changing the line that defines its location in WEB-INF/web.xml.

WEB-INF

The servlet deployment directory contains a web.xml file for the JWAA servlet and a lib directory. The lib directory contains jwaa.jar with jwaa's java components plus the libraries that jwaa.jar depends on. These include the latest versions of commons-collections.jar, gnu-regexp-1.1.4.jar, jaxen-core.jar, jaxen-jdom.jar, jdom.jar, junit.jar, jwaa.jar, log4j-1.2.8.jar, mysql-connector-java-3.0.10-stable-bin.jar, saxpath.jar, velocity-1.5-dev.jar, xerces.jar, and xml-apis.jar. All are standard packages except for velocity. The a pre-release version is included which repairs an incompatibility between Velocity and XML entity syntax by accepting "and" as a synonym for the problematic &&.

sql

This directory contains a MySQL script that you'll use to define the JWAA database.

src

This directory contains the source for the Java components of the JWAA distribution

index.html

The JWAA home page is distributed as a conventional static html file, index.html. Confirm that this page is accessible at the url http://localhost/jwaa . The links inside this page will not be accessible until Apache has been configured to route them to the servlet engine and the servlet engine has been configured to route them to the JWAA servlet.

Once these configuration steps have been completed, the JWAA home page will also be accessible as a dynamic page at the URL http://localhost/jwaa/xml/jwaa/OUTER . The index.html file is periodically generated by browsing the dynamic URL and saving the result as index.html. This ensures that the home page is accessible even when the servlet engine is down and makes this page accessible to search engines that might be unable to access servlet-based pages.

MySQL Initialization

These instructions assume that MySQL has been installed by following its own instructions and is working propertly. All that remains is defining a database for JWAA to use, defining a MySQL user with ownership rights for that database, assigning that user a secure password, and conveying this information to JWAA by editing jwaa's application.xml file.

The sql directory contains a sql script, initialize_jwaa_database.sql. This script initializes the jwaa database (dropping any existing one; careful!) and creates a user, jwaa, with full permissions on that database. Edit the script before using it. AT THE VERY LEAST change the password to something secret! Then run the script by typing:

mysql <sql/initialize_jwaa_database.sql

Then specify the same password in the jdbc section of root/jwaa/application.xml. JWAA uses JDBC and should work with any database but this has not been tested.

See the configuration instructions for how to configure these systems to work together properly.