Setting up the SystemInstallationSetting up the components

Software Components

The following components are required to install this system:

Apache Tomcat

This is the dynanic web page server around which this system is built. It is fundamental component. This may exist on your system, but it can be obtained from http://jakarta.apache.org/tomcat/. The current system is designed around version 5 of Tomcat, and the Ant "build.xml" script may need changing if a newer release is used. The ExerTran system can work within an existing Tomcat installation serving other applications, but it may be easy to manage if a separate Tomcat installation is set up for a coursework or courseworks managed by a single person.

Mysql or other database server

The system is known to work with Mysql and has an Java Object "system.MysqlInterface" already built to interface to Mysql. Using a different database will require an interface object appropriate to this database to be built, although "system.MysqlInterface" should provide a template for this. Any such object must be derived from "system.DBConnection". Again, an existing database installation may be used as ExerTran only requires to access a single database within the server, although a new installation may reduce security issues on access to marks and mark tables.

Apache Ant

This is required to build the system from the sources, although this could be done manually. There is no "make" script for building the system. Ant is available from http://ant.apache.org/. An existing installation is suitable here.

CVS

The current ExerTran system is stored in a CVS repository and the most suitable way to get a copy of the software is via cvs. An existing CVS installation is suitable, but otherwise CVS can be obtained from http://www.cvshome.org/. A windows version of CVS, "winCVS" can be obtained from http://www.wincvs.org/.

None of the above software is difficult to install, and there is ample documentation on installing and testing the instalation, so this is not covered here. Installation details specific to running the ExerTran system are detaild in the next section.

The following details relate to setting up the different components of the system:

software

This software can be accquire once CVS has been installed. The environment variable CVSROOT has to be set up prior to checking out a copy of the software. On a Unix system, the environment variable can be set temporarily on the command line or can be set up longer term via something like the ".bash_profile" file if the "bash" shell is being. Similarly, this variable has to be set into "wincvs" on a Windows box.

The current CVSROOT string for anonymous access can be found on my web site. The command sequence to get the software is


   CVSROOT=whatever_is_on_the_web_site
   cvs export -d install_directory elecTran
 
This will install the code within the install_directory that you specify. This does create any CVS files for checking the code back into the repository. Any directory that suits you may used. If the "-d install_directory" are missing from the export command, the install directory will be "elecTran".

If the code is successfully, then you should set up Apache ant so that you can create a coursework in order to move to testing the system. This last is described in , and the command to execute on the command line from within the install directory is:-


      ant -DappName=course_name createnewcourse
where again you specify a course name or number: a single word is usual. This will create a "Home" directory for the coursework and particular a coursework definition file. If the coursework is named "D2", then this file will be in the "courses/D2Home.D2.def". This definition file should be edited and parameters filled in appropriate to your installation.

At this point, the Tomcat and Mysql systems should be set up.

Apache Tomcat

Once, the Tomcat system has been installed and tested, there are some minor changes normally required. These are to enable https access and to change the port number used by Tomcat to listen to requests. These changes are made to the "server.xml" file in Tomcat's "conf" directory: the path to this file from the Tomcat installation directory is "conf/server.xml".

To enable https access to Tomcat the second and last line of the following code should be removed:-


 
    <!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
    <!--
    <Connector port="8443" 
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" debug="0" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />
    -->
 
 
This uncomments the "Connector"statment allowing https access.

Tomcat comes with default port numbers for its various services: 8005(shutdown), 8009(coyote), 8080(http), 8082(proxy), 8443(https). It is easy for there to be a conflist between two or more Tomcat installations running on the same machine if these defatult port numbers are used. You may have had a problem already in testing your Tomcat installation. It is best to choose some other set of numbers for the services on your Tomcat installation by editing these values in "conf/server.xml". Note that each service should have a different number and that numbers above 6000 should be used, below these are public port numbers. Once you have doe this you should run Tomcat to see that you canstill run Tomcat.

If you are running the system on a headless server, no X windows screen attached, and you intend to display dynamically generated images, then you need to set up a vncserver to provide an X interface for the generation of the images. Running this is described below, but at this stage if this is to be done, the Tomcat start-up script, ("bin/startup.sh"), needs to be edited so that Tomcat can be started with the display number for the running "vncserver", see . My version of "bin/startup.sh" is:-


#!/bin/sh
umask 077
DISPLAY=:$1; export DISPLAY
echo using DISPLAY=$DISPLAY
CATALINA_HOME=/opt/UCLCScourseware/java/tomcat/jakarta-tomcat-5.0.28
CATALINA_BASE=/cs/academic/staff0/marine/ucacpar/TC
export CATALINA_HOME CATALINA_BASE
$CATALINA_HOME/bin/startup.sh
This sets the DISPLAY environment variable with the running "vncserver" display number.

Mysql or other database server

For the database server, it is necessary to determine the port number that it listens on for remote accesses: Tomcat talks to the database server on this port number over the network. For Mysql, the port number is given in the "safe_mysqld" section of the ".my_cnf" file in the Unix home directory: for Unix the port number is specified on a line thus "port=6303". For Windows, the default port number for Mysql is 3306. Again, if other users mught be running a similar dtabase, it is best to change the port number from the default value, again to some high number.

Having discovered or changed the port number, it must be entered into the coursework definition file along with the name of the machine on which the server is to be run, the name of the database, its interface class, and the name of the JDBC database driver. This is as follows for a Mysql database:-


dbServer=mysql
dbClass=MysqlInterface
dbDriver=org.gjt.mm.mysql.Driver
dbHost=localhost
dbPort=29784
 
where "localhost" is used for the host name as Tomcat and Mysql execute on the same host.

Setting up users and tables on the database

At least 2 users are required on the database besides the "root" user: it is not advisable to use the root server from Tomcat. One of these users will have write privileges to the database and the other will have read privileges on just the user and password table. Before doing this a database must be defined for the coursework, and a minimal user-password tableet in the database. The actions in setting these up are explained below for a coursework with name "D2" for a Mysql database.

The database should be set up with a name relatd to the coursework: it could be the same as the courework name or number. To create the database with name "D2", the following Mysql code is executed as root at the prompt "mysql>":-


        create database if not exists D2; 
 
The database can then be entered with the command:-

        use D2 ;
 

A user-password table can be then be created with the command:-


create table if not exists users (user VARCHAR(50) NOT NULL PRIMARY KEY, password VARCHAR(50) NULL, role VARCHAR(20) NULL) TYPE=MYISAM;
 
This creates a table with the default name and structure as defined in the /src/xml/users_def file that describes the structure of this table, i.e. the table is called "users" with 3 columns named "user", "password" and "role". The table definition in /src/xml/users_def and used in the above command must agree as to the number and names of columns. This table must be populated with at least one user with role "manager". I usually do this by entering the data for the user in a file with the users data single line and tab separated:-

f.bloggs        washingUp      manager
 
where the user name is "f.bloggs" with password "washingUp" and with role "manager". This file can be loaded into Mysql using the command:-

        load data local infile "path_to_file" ;
 
This should populate the "users" file, which can be checked with the Mysql command:-

        select * from users ;
 

The two non-root users can be set up with the following Mysql commands:-


grant usage on *.* to tomcatUser@amy.cs.ucl.ac.uk identified by 'fridayAfternoon' ;
grant select on D2.users to tomcatUser@amy.cs.ucl.ac.uk ;
GRANT ALL PRIVILEGES ON D2.* TO p.rounce@amy.cs.ucl.ac.uk IDENTIFIED BY 'washDayBlues' WITH GRANT OPTION;
 
where "tomcatUser" will be the low privilege user for reading the user-password table when making https connections to the coursework system. The first line creates the user "tomcatUser" with password "firdayAfternoon" to the Mysql server, while the second line give read-only access to "tomcatUser" to the "users" table of database "D2".Note that the "@amy.cs.ucl.ac.uk" restricts "tomcatUser" to accesses from host "amy.cs.ucl.ac.uk": this must be the host on which Tomcat is running the coursework - use "@localhost" if the database and Tomcat run on the same machine. Th last line create user "p.rounce" with Mysql password "washDayBlues" with all privileges to access the database table from the Tomcat host "amy.cs.ucl.ac.uk": again this should be "@localhost" if the database and Tomcat run on the same machine. The capitals are not important in the commands for the Mysql keywords, but the apsostrophes are.

Once the above has been done, the details of the database table, and the table names for the user and other tables, and the name and password for the low priority user, "tomcatUser" and <, and quote>fridayAfternoon must be entered into the coursework definition file:-


dbName=D2
dbUsersTable=users
dbQuestionsTable=cwquestions
dbMarksTable=qumarks
tomcatUser=tomcatUser
tomcatUserPassWord=fridayAfternoon
 

Building the first coursework

Once the above has been done, Tomcat and Mysql have been set up and their port numbers modified as necessary, a database for the coursework has been set up with a user-password table with a manager entry added.

None of the above software is difficult to install, and there is ample documentation on installing and testing the instalation, so this is not covered here. Installation details specific to running the ExerTran system are detaild in the next section.