Install the source distribution

Make sure you have downloaded all of the required technologies somewhere on your computer. Then follow these steps:
  1. Unzip the source bundle in some read/write-able location on your computer. For purposes of explanation, let us assume that directory is called ajaqs.

  2. Modify ajaqs/build.properties to reflect the location of various .jar files on your computer.

  3. Copy c.tld, fmt.tld, and fn.tld from the JSTL distribution and put them under ajaqs/web/WEB-INF.

  4. Copy request.tld from the jakarta-request-1.0.1 distribution and put it under ajaqs/web/WEB-INF.


Create back-end

To set up the back-end, do this:
  1. Make sure your database vendor is supported. You can verify this by looking in the ajaqs/sql subdirectory and seeing if there is a directory there with SQL scripts for your vendor.

  2. Create the database you identified in build.properties.

  3. Make sure a connection from your computer to the database is possible.

  4. Make sure the database administrator and user (and their passwords) that you specified in build.properties are properly set up in your database. In particular, make sure these users have suitable access restrictions with respect to the database tables you intend to set up for Ajaqs.

  5. Run: ant dbcreate -f build.xml.

  6. Run: ant dbinit -f build.xml. This will create various tables in the database. See the Ajaqs E-R Model for a more thorough explanation of what data is represented by the tables.


Testing the back-end

This is an optional step mainly intended for developers. If you wish to validate your database.xml configuration, follow these steps:
  1. Download the jar file for Jakarta Commons Logging. Put the jar file in some place where it will be found when Ajaqs starts. In my setup, I just copied the jar file into /path/to/tomcat/common/lib. NOTE: when you are finished with testing the back-end, move the Jakarta Commons Logging jar file out of Tomcat's common/lib. It is not required for Ajaqs, and it may lead to exceptions when Ajaqs starts (which is what I observed on my setup).

  2. Modify build.properties and set correct file locations for the xerces.jar and commons.logging.jar properties.

  3. Run ant xmlinit to set up XML configuration files under the build sub-directory.

  4. Run ant test. This test will load database.xml and try to set a few records in your database. If something goes wrong, then it is likely some part of your setup needs to be corrected. Be cautioned that when you run this test more than once, you may run into errors. You can work around this problem by always clearing the database before running ant test. See the source file test/com/beardediris/ajaqs/db/MappingTest.java for details.


Initialize Ajaqs

At this point, you should initialize the back-end with certain data required by Ajaqs at startup. This includes an initial set of users, roles, projects, and FAQs. Eventually, you will be able to create much of this data from a browser, provided you have admin priveleges; as of this writing, such support is not available.

To prime the Ajaqs back-end with test-data, run ant dbinsert -f build.xml. This uses the SQL script ajaqs/sql/mysql/insert_data.sql to load various test data in a MySql database. For more specific types of initial data, you will need to create your own SQL script, similar to insert_data.sql, and use that script to prime the Ajaqs back-end.


Configure webapp server

If you are using Tomcat, you should look at ajaqs/xml/tomcat/server.xml. Find the Context in which the Ajaqs webapp is configured. Put this Context somewhere in your webapp server's configuration file. In Tomcat 5.x, such configuration is found in tomcat/conf/server.xml.

Pooling with MySQL

To pool connections to a MySQL database, take the following steps:
  1. Download the jar files for Jakarta Commons DBCP, Jakarta Commons Pool, and Jakarta Commons Collections. See the required technologies section for links to these packages.

  2. Put the jar files in the CLASSPATH for Ajaqs. In my setup with Tomcat 5.x, I just copy the jar files into /path/to/tomcat/common/lib.

  3. In the webapp configuration file ajaqs/web/WEB-INF/web.xml, make sure you specify databasePooled.xml, rather than database.xml, in the appropriate place so that you use the pooling configuration.


Pooling with PostgreSQL

To pool connections to a PostgreSQL database, just specify the postgresql.xml configuration in the mapping.xml file; this setup provides JDBC pooling. I have not yet tested this configuration against PostgreSQL as of Ajaqs version 1.1.2.