Deploying Examinator

Introduction

The figure at left (click to enlarge) shows a small Terracotta server array that could be implemented to run Examinator and provide High Availability. This cluster configuration has the following components running on separate machines:

• An active Terracotta server instance
• A "hot standby" Terracotta server instance
• Two application servers (Terracotta clients)
• An active load balancer
• A backup (redundant) load balancer
• A MySQL database application

The application servers must have access to an SMTP server, which can be remote. In the example at left, the SMTP server is located in the cloud.

For more information on deployment, see the following resources:

• Supported Platforms – A list of software certified to work with Terracotta. While a certified platform is not an absolute requirement for using Terracotta, you can use this list and the information in this deployment documents as guides.
• Configuring Terracotta For High Availability in Terracotta Product Documentation – Configuring a cluster for high availability. This document contains configuration and testing advice.
• Deployment Guide – General information on deploying Terracotta.
• Examinator Quick Start – Instructions on how to get and use the Examinator package. The fastest way to deploy Examinator.
• Examinator Maven Project – See this short tutorial for information on how to deploy Examinator with Maven. Also shows how the various components in an Examinator deployment fit together.

Hardware

Examinator can be deployed using commodity hardware.

Minimum Hardware Requirements

Recommended Hardware

Software

Examinator can be deployed using open-source software. The configurations shown were used in our Examinator deployment, but variations are possible.

• Terracotta Server Instances: Linux, JDK 1.6 (1.5 acceptable), Terracotta 2.7.2 (or the latest version available from www.terracotta.org)
• Application Servers: Linux, JDK 1.6 (1.5 acceptable), Tomcat 6.0, Terracotta 2.7.2 (must match version run on Terracotta server instances)
• Database Servers: Linux, MySQL 5.0
• Load Balancers: FreeBSD, relayd (set for sticky TCP sessions with health checking)

Another good choice for load-balancing in a production environment is Apache httpd with mod_proxy or mod_jk.

Once you install the software listed above, continue with the following sections.

Configure Terracotta

You can download a Terracotta configuration file (tc-config-prod.xml) that has been modified for use with Examinator. Edit the "name" and "host" attributes of the two <server> elements, one for each Terracotta server:

• name – A unique name for the Terracotta server.
• host – The hostname (or IP address) of the server's machine.

See the following documents for more information on configuring Terracotta clusters:

• Configuring Terracotta DSO – The configuration process explained.
• Working with Configuration Files in Terracotta Product Documentation – How Terracotta configuration files are used with Terracotta server instances and clients (application servers).

You can also edit the paths in the following properties to match your setup requirements:

• <logs> – The location where Terracotta servers or clients write log files.
• <data> – The location where Terracotta servers store shared data.
• <statistics> – The location where Terracotta servers or clients write operational statistics.

Install Examinator

Use Subversion (version 1.4 or 1.5.x) to download the Examinator package:

svn co http://svn.terracotta.org/svn/forge/projects/exam/tags/release-1.0.1 exam

To see the latest version of Examinator, use the Subversion list command: svn list http://svn.terracotta.org/svn/forge/projects/exam/tags Then replace "release-1.0.1" in the download URL to the version you want.

After a successful download, a project directory called exam should appear in your current directory. Change to the exam directory and use Maven (version 2.0.9) to compile:

mvn -Pprod-build -Dexaminator-host=<localHostName> -Dexaminator-port=<portNumber> clean package

where <localHostName> is the hostname of the active load balancer and <portNumber> is the TCP port used to connect to that load balancer.

Be sure to set the examinator-host and examinator-port properties to avoid the sending of Examinator emails with incorrect URLs embedded in them.

Set Up the Database

The exam project defaults to using the MySQL root account and connecting to the database at localhost:3306. With MySQL running, set up a new database user to avoid using the root account. You can change the values of any of these parameters in the POM file or using command-line flags.

In the following examples, the database user is called "exam" and has the password "myPassword". The database instance is running on the local host on TCP port 3306.

POM File

Change the following properties in the exam project's pom.xml file:

<db-user>root</db-user>
<db-passwd>myPassword</db-passwd>
<db-host>localhost</db-host>
<db-port>3306</db-port>
<db-name>exam</db-name>

Use the following command to create the Examinator database:

mvn compile hibernate3:hbm2ddl

Command-Line

If you do not edit the POM file, use the following command to create the Examinator database:

mvn -Ddb-passwd=myPassword -Ddb-user=exam compile hibernate3:hbm2ddl

Configure Examinator to Use an SMTP Server

Examinator requires access to an SMTP mail server to send confirmation emails for new accounts. You configure an SMTP server in the mail.properties file located in <maven projects directory>/src/main/filtered-resources.

Do not allow outside access to the Examinator until you set up the initial admin account. The first connection to Examinator, even if remote, establishes the initial admin account. There are no default user accounts.

You must edit the following properties:

• examinator.from.email – An email address that represents the sender.
• smtp.host - The address of any available SMTP server.

The remaining properties in mail.properties set the text that appears in the subject of different types of emails. A configured mail.properties file should appear similar to the following:

examinator.from.email=Support@MyCompany.com
smtp.host=mail.MyCompany.com
subject.signup.confirmation=Welcome to Examinator
subject.password.reset.confirmation=Password reset confirmation
subject.password.reset.done=Your password has been reset

Start the Cluster

With MySQL running, start the cluster in the following order:

1. Active Terracotta server instance
2. Standby Terracotta server instance
3. Application servers
4. Before allowing outside connections, set up the initial Examinator administrator account.
   Using a web browser, connect to Examinator (for example, locally with the URL http://localhost:8080/examinator). You will be prompted to set up the first account, which serves as the first administrator account.
5. Once the initial account has been set up, start the load balancers and allow outside connections.