Project Setup

Headmaster consists of three primary runtime components: the database, the web service, and the client web application. Setup instructions are provided in that order.

Database Setup

1. Download, install, and start up your chosen relational database server.

2. Initialize Headmaster’s destination database/namespace/schema.

   For PostgreSQL, this means invoking createdb <database name>.

3. If you want to run the unit tests, you should also create a separate database/namespace/schema for these tests.

4. See below for instructions on how to initialize the database schema.

Web Service Setup

To build and deploy:

1. Copy SAMPLE-build.properties to build.properties.

2. Fill in the database username, password and any other missing properties that don't get checked into the repository.

   You will need to create two empty databases: one for production and another for testing. The testing database is touched during the build sequence, when unit tests are run.

3. If you have not initialized a production database yet, set the build.properties file’s hibernate.hbm2ddl.auto property to create:

   `hibernate.hbm2ddl.auto=create`

   There is no need to initialize the testing database because the build sequence initializes it for you.

4. Install a log4j.xml in src/main/resources if desired. A SAMPLE-log4j.xml starting point is available at the project root.

5. mvn clean package

6. Your war file is in target/: deploy as you wish.

   For Tomcat, this means copying the war file to $TOMCAT/webapps.

7. Configure your app server for authentication. For Tomcat, do this:

   1. Copy the PostgreSQL JDBC library to $TOMCAT/lib.
   2. Edit $TOMCAT/conf/server.xml.
   3. Replace or comment out this block*...*

   <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase"/>
    

   4. ...with this block (note the substitutions):

   <Realm className="org.apache.catalina.realm.JDBCRealm"
               driverName="org.postgresql.Driver"
               connectionURL="jdbc:postgresql://***database/host/and/name***"
               connectionName="***database-username***"
               connectionPassword="***database-password***"
               userTable="serviceuser"
               userNameCol="login"
               userCredCol="challenge"
               userRoleTable="userrole"
               roleNameCol="rolename"
               digest="sha-512"
        />
    

8. Start up your app server.

   • For Tomcat, this means running $TOMCAT/bin/startup.sh.
   • If you run into memory issues with Tomcat, create the file $TOMCAT/bin/setenv.sh with the following content:

   JAVA_OPTS="-Xmx1024m -XX:MaxPermSize=512m -XX:PermSize=512m -XX:+CMSClassUnloadingEnabled"

9. If you set hibernate.hbm2ddl.auto=create, this first run will have initialized the database schema and loaded it with some startup data. Stop your app server ($TOMCAT/bin/shutdown.sh for Tomcat), change this setting to hibernate.hbm2ddl.auto=validate in build.properties, then rebuild and redeploy the war file.

10. URIs to try in your browser (the default initial user is headmaster with password headmaster:

• http://localhost:8080/headmaster/users/login/headmaster
• http://localhost:8080/headmaster/students?q=jones
• http://localhost:8080/headmaster/events?q=convo

The latter two service calls will return 404s until you add data that match those queries, but at least they will show you that things are up and running.

11. For other methods like PUT and POST, you'll want to get Poster, curl, or any other web service capable HTTP client.

12. If you are using Eclipse, designate the following as source folders:

• src/main/java
• src/main/resources
• src/test/java
• src/test/resources
• target/generated-sources/jaxb

Client Web App Setup: Tomcat Standalone

1. Copy SAMPLE-build.properties to build.properties.

2. The main property to set for the client is service.root: i.e., the root URL for the web service. The default value service.root=http://localhost:8080/headmaster/ denotes that the web service is hosted by the same machine as the web app with /headmaster at the top of the URL's path.

3. The wicket.deployment property is specific to Apache Wicket, which is the framework used by the client web app. Please refer to http://wicket.apache.org for details on Wicket development and deployment builds.

4. Install a log4j.xml in src/main/resources if desired. A SAMPLE-log4j.xml starting point is available at the project root.

5. mvn clean package

6. Your war file is in target/: deploy as you wish.

   For Tomcat, this means copying the war file to $TOMCAT/webapps.

7. Point your web browser at http://hostname:8080/headmaster-client.

Client Web App Setup: Quick-Run with the Tomcat Maven Plugin

For quicker client web app development turnaround, you can run the client web app directly from Maven through the Tomcat Maven Plugin. You still need access to a Tomcat instance that is running the web service, but that service runs independently of the client web app.

1. Follow steps 1-4 in the Client Web App Setup: Tomcat Standalone section above.

2. mvn tomcat7:run

3. Point your web browser at http://hostname:9090/headmaster-client, where hostname is the machine that is executing mvn tomcat7:run (e.g., localhost if you are doing everything on one computer).

   Note the distinct port number, to avoid conflicts in case you are also running standard Tomcat on your machine.

4. Hit Ctrl-C to stop the server.