Table of Contents
This section explains how to install the SubmitServer component of Marmoset. The SubmitServer is a web application that stores submissions, allows students and instructors to view submissions and their outcomes, and facilitates automated testing by one or more BuildServers.
The goals of this document are to specify how to set up and run a SubmitServer instance. This includes configuration information for a Tomcat installation where the SubmitServer can be deployed (typically by dropping a submitServer.war file into a certain directory).
To install and run the SubmitServer, you need the following:
The
SubmitServer ModuleandSubmitServerModelClasses Moduleincluded in the installation distribution.A machine installed with Linux.
JDK 1.5 (a.k.a. 5.0) or later ( Download Java ).
Ant 1.6 or later ( Download Ant, Note that ANT is included with the Eclipse IDE)
-
MySQL 4.1.16 or later (
Download MySQL
). Section 3, “Installing MySQL and the database for Marmoset” will describe the MySQL installation process.
Marmoset has been tested successfully using mysql-standard-4.1.16-pc-linux-gnu-i686-glibc23 and mysql-standard-5.0.22-linux-i686-glibc23.
Jakarta Tomcat 5.5.9 or later ( Download Tomcat ). Section 5, “Installing Jakarta Tomcat” will describe the Tomcat installation process.
![[Note]](note.png)
Note When configuring Tomcat to use SSL with a self-signed certificate, you will need write access to some parts of your Java (JRE) installation. See Section 5.3, “Configuring SSL” for more information.
| Note |
|---|---|
| You will almost certainly want to put MySQL and tomcat onto the same machine because it's more secure to only allow connections to the database only from localhost (than to try to deal with MySQL+SSL). |
| Note |
|---|---|
| The MySQL database and Tomcat can both run as any user account. For security purposes, it's not a good idea in general to run either of these as the root user of the unix system. Also keep in mind that the 'root' user of the unix host machine is not the same thing as the 'root' user of a MySQL installation. These are two separate, unrelated concepts that happen to have the same name. You can connect to the MySQL database as the root database user using any unix user account. |
| Note |
|---|---|
| It is NOT recommended to install either MySQL or Tomcat onto an NFS-mounted volume. Doing so almost guarantees problems with stale NFS-filehandles, problems locking files, and so on. |
If you have not already done so, extract the Marmoset distribution from the distribution archive.
Extract both the SubmitServer
and SubmitServerModelClasses archives into the same
directory -- this directory will be the base for your installation. (E.g.
$HOME/projects/submitserver.) If you are using Eclipse,
this directory will also be the workspace.
You should now have two directories:
$SUBMITDIR/SubmitServer2, and
$SUBMITDIR/SubmitServerModelClasses
where $SUBMITDIR is the directory you extracted the archives into.
The next few sections will describe the installation of MySQL, the Submit Server Database, and Tomcat. These should be installed on the host that you want to run the Submit Server. Then we will return to this directory to configure and install the Submit Server.
If MySQL is not already installed on the host system, simply download and untar a binary distribution from http://dev.mysql.com/. Point the shell variable MYSQL_HOME at your installation. Then put $MYSQL_HOME/bin and $MYSQL_HOME/scripts on your path.
For example, you could untar MySQL into $HOME/software/mysql and then (assuming your shell is bash) do:
export MYSQL_HOME=$HOME/software/mysql export
PATH=$MYSQL_HOME/bin:$MYSQL_HOME/scripts:$PATH
Even with MYSQL_HOME clearly pointing to the MySQL installation, MySQL still seems to assume that it got put into /usr/local.
So, edit $MYSQL_HOME/bin/mysqld_safe (the daemon program that starts/stops mysql) by finding the following lines (located at lines 106-107 for mysql-standard-4.1.16-pc-linux-gnu-i686-glibc23):
MY_BASEDIR_VERSION=/usr/local/mysql
ledir=/usr/local/mysql/bin
and then replacing them with this:
MY_BASEDIR_VERSION=$MYSQL_HOME
ledir=$MYSQL_HOME/bin
I have no idea why this is necessary, and rather than trying to figure out why, I just make this change everytime I install MySQL since it works. If anyone knows a better way to do this (i.e. without editing the mysqld_safe file) please send email to
<jspacco@cs.umd.edu>.All of the database-related scripts for Marmoset are located in SubmitServerModelClasses/dbScripts (in the Submit Server directory we created in Section 2, “Unpack Submit Server Components”. I will hereafter refer to the SubmitServerModelClasses/dbScripts/ directory as simply dbScripts. You need to add this directory to your path.
Note You may also need to change the permissions to make runsql, fresh-install, start-innodb, and stop-innodb executable. In general, jarfiles (and I think zipfiles) won't preserve file permissions, due to compatbility issues between file systems that don't use the same types of permissions for controlling access to files. If you're not that familiar with MySQL and are installing a fresh database, don't worry, as we provide a script that will create and startup a fresh database.
You can do this by simply going into the dbScripts directory and running the following command:
./fresh-install <database password> <directory for database> [ -p <port> ] [ -d <database> ]The <directory for database> can be anywhere on the local file system. It is NOT A GOOD IDEA to put the directory on an NFS-mounted volume. This will almost certainly cause annoying problems with stale file handles and file locks.
The <database password> you pick will be for the root database user. Note that the root database user account is not the same thing as the root unix account on the machine you're running the database. This password will allow you to access the database as root using any unix user account.
The <port> is an optional parameter that will change the port used by MySQL. If you don't set a parameter here, it will use the default, which is port 3306.
The <database> parameter will change the name of the database. The default name is submitserver .
This will create and start a new database, and set the root password to what you picked. This will also create a $HOME/.my.cnf file, the hidden file MySQL uses to store configuration information necessary (like username, passwords, paths to the database socket file, etc) to log into the database.
NOTE: The $HOME/.my.cnf file contains your root database password so make sure the file is not visible to anyone that shouldn't be able to see it. The fresh-install script will try to set the file permission so that group and others can't see the file (chmod og-rwx).
Make sure that creating and starting the database worked by running the mysql command line program:
mysql
You should see a prompt that looks something like this:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 5 to server version: 4.1.16-standard-log
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql>
Once you see the prompt, to quit mysql, you just type 'quit'.
Note The fresh-install script also starts the database server. If the mysql command fails with error: "Can't connect to local MySQL server", it is likely the database server has not been started. Do this manually by running the dbScripts/start-innodb script. The only required parameter is the directory where the database is installed (i.e. the directory used in the ./fresh-install command above): ./start-innodb <directory for database>Next you need to create all the tables according to the Marmoset database schema. Again, go into the dbScripts directory and run this command:
./runsql marmoset-schema.sqlThe runsql script is a useful script that will run any *.sql script against the database referred to in the .my.cnf file.
The next step is to update the basic schema using a patch script located in the sql-patches directory. Use the command:
./runsql sql-patches/project-starter-file-archives.sqlNow run the mysql command line program again, and make sure that the database you created exists (by running '
show databases;') and that the tables for the database also exist (use 'show tables;'). Refer to the MySQL reference manual (http://dev.mysql.com/doc/) for more information about querying MySQL from the command line.
The first thing you need to do after creating the database is create a superuser account that you can use to log into the system and bootstrap the rest of the installation process. You need to do this directly in the database, because all operations done by Marmoset require authentication against the database. It's kind of a chicken-and-egg problem.
Find and edit the file SubmitServerModelClasses/dbScripts/bootstrap.sql. The file will look like this:
INSERT INTO students VALUES (DEFAULT, 'campus_uid',
'employee_num', 'firstname', 'lastname', 'yes', DEFAULT,
DEFAULT, DEFAULT, 'password');
You need to set a value for each non-DEFAULT column. Each column is described in the following table.
Table 3.1. Important values for the Marmoset super-user account
| column | description | |
|---|---|---|
| campus_uid |
A campus-wide unique identifier for each account.
This is typically a unix login, but can anything
else. Values in this column
MUST BE UNIQUE.
You will see the terms "directoryID" and "campus_uid" used interchangably in the submitServer. This is a Maryland-ism that I hope to factor out at some point. | |
| employee_num | Maryland-specific database field that stores the employee number (our campus-wide database uses the ambiguous term "employee number" even though students as well as staff and faculty are identified by this number). If you are using the GenericStudentPasswordAuthenticationService then set the employee_num to the same value as the campus_uid. The employee_num does NOT need to be unique. | |
| firstname, lastname | The person's firstname and lastname | |
| yes | This is the super-user permissions column. Leave it as 'yes' so that the superuser account has superuser permissions. | |
| password | The password to be used by the GenericStudentPasswordAuthenticationService. This is the password you will use to login. |
Once you've finished editing the bootstrap.sql script, run it like this:
cd SubmitServerModelClasses/dbScripts
./runsql bootstrap.sql
This will create the superuser account you can use to start creating courses. You can check this by opening the database and selecting the contents of the students table in the database:
select * from students;
How to install tomcat
Unpack Jakarta Tomcat 5.5.9 ( Download Tomcat ) or higher into a directory on the host that will run Submit Server. Note that Tomcat should go into a local part of the filesystem; it is a VERY BAD IDEA to put Tomcat in a directory on an NFS-mounted volume. Doing so practically guarantees problems from stale NFS-filehandles and so on. We know from experience; just don't do it.
I always symlink $HOME/tomcat to whereever I've unpacked tomcat. From this point on I will refer to this directory simply as
Tomcat, or theTomcatdirectory.
The file Tomcat/conf/server.xml contains (among other things) configuration information for the various ports Tomcat will listen on for incoming connections (i.e. 8080 for http, 8443 for https, etc).
You need to find this chunk of xml:
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="true"
xmlValidation="false" xmlNamespaceAware="false">
And then add this underneath it:
<Context path="" docBase="submitServer" debug="0"
reloadable="true"/>
This will make sure that the submitServer context is the default context (thus you can simply access https://foo.cs.umd.edu:8443 rather than https://foo.cs.umd.edu:8443/submitServer)
Also, there's tons of documentation on Tomcat on the web , so feel free to look there for more info on what all of the other stuff in server.xml and web.xml are there for, I don't actually know what every feature does.
The file Tomcat/conf/web.xml contains (among other things) a
series of
context-param
nodes specified as children of the root
web-app
element. These are initialization parameters that are passed to
your web application. You want to configure any resources here
that are specific to this particular tomcat installation (for
example which database this tomcat installation will be connecting
to). This is useful because you may have a development Marmoset
installation with one database, and a production installation with
its own database.
| Note |
|---|---|
You can also configure context-param resources in
SubmitServer2/lnf/web.xml.
In general, I've put things
that are the same for all installations into
SubmitServer2/lnf/web.xml while I've put things that
vary in Tomcat/conf/web.xml.
This also keeps things like database
passwords from being checked into CVS.
|
| Note |
|---|---|
During installation, the file SubmitServer2/lnf/web.xml
is copied into SubmitServer2/WebRoot/WEB-INF/web.xml,
which is later copied into the Tomcat WebRoot. Hence when setting
properties for all installations, you should modify
SubmitServer2/lnf/web.xml instead of
SubmitServer2/WebRoot/WEB-INF/web.xml.
|
DO NOT set the same context-param in BOTH Tomcat/conf/web.xml and SubmitServer2/WebRoot/WEB-INF/web.xml. This will cause your web-application to fail upon startup.
web.xml is (obviously) an xml file. A context-param looks like this:
<context-param>
<param-name>authentication.service</param-name>
<param-value>edu.umd.cs.submitServer.GenericStudentPasswordAuthenticationService</param-value>
</context-param>
You need to make sure you set the following context-params in Tomcat/conf/web.xml (replace PASSWORD with the database password you chose when you configured MySQL, of course):
<context-param>
<param-name>authentication.service</param-name>
<param-value>edu.umd.cs.submitServer.GenericStudentPasswordAuthenticationService</param-value>
</context-param>
<context-param>
<param-name>database.server.jdbc.url</param-name>
<param-value> jdbc:mysql://localhost/submitserver</param-value>
</context-param>
<context-param>
<param-name>database.user</param-name>
<param-value>root</param-value>
</context-param>
<context-param>
<param-name>database.password</param-name>
<param-value>PASSWORD</param-value>
</context-param>
<context-param>
<param-name>database.driver</param-name>
<param-value>org.gjt.mm.mysql.Driver</param-value>
</context-param>
There are several other context-params than you can set in this file:
Table 3.2. Valid Marmoset context-params
| name | values | required? | default | description |
|---|---|---|---|---|
| authentication.service |
edu.umd.cs.submitServer.SERVICE
where SERVICE is
MarylandAuthenticationService
or
GenericStudentPasswordAuthenticationService
| no | MarylandAuthenticationService |
The name of the class to be used for
authentication purposes. The web app will use
the string name given here to dynamically load
the class, create an instance of that class,
and use the class for authentication. The
GenericStudentPasswordAuthenticationService
authentications against the password stored in
'password' column of the 'students' table in
the database; this is suitable for most
environments. You could also implement your
own authentication service by providing an
implementation of
edu.umd.cs.submitServer.IAuthenticationService
and then providing the name of your
implementation.
|
| perform.background.retesting | true|false | no | false | Should Marmoset keep re-testing submissions in the background in order to get more confidence in the results? Useful for multi-threaded code. |
| semester | String e.g. Spring 2006 | no | N/A | If this parameter is provided, the semester indicated is the default value of the "semester" field in the "Create course" form. Chapter 9, Configuring Marmoset describes creating a new course. |
| DEBUG | true|false | no | false | Indicate whether more detailed logs should be created during the run of Submit Server. Logs are created in the Tomcat/logs/marmoset directory and keep track of things like authentication failures and other errors. The logs created when this is set to true are quite extensive, so set this to false unless you want to do some debugging. |
To prevent Tomcat from listing the contents of directories, find this chunk in web.xml and make sure that "listings" is set to "false", like this:
<servlet>
<servlet-name>default</servlet-name>
<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>false</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
You probably want to configure Tomcat to use SSL so that you can transmit secure traffic between clients and the server. This is especially important if you are communicating over wireless connections, where sniffing packets is quite easy.
There are two types of certificates that you can use: a signed certificate and a self-signed certificate.
A signed certificate is a certificate that has been signed by a recognized Certificate Authority (CA) and will be accepted by most browsers or client programs. These certificates are valid for a certain amount of time, such as one year, and typically cost money.
A self-signed certificate is a certificate that you can produce and sign yourself using Java or another program.
![[Warning]](warning.png) | Warning |
|---|---|
| Self-signed certificates are not automatically accepted by client programs. Browsers will typically ask the user whether they want to accept the certificate or not, while some client programs such as Java will simply refuse to accept an unsigned certificate unless that certificate is explicitly imported by the user. |
The following section assumes that you are using a self-signed certificate . The steps for using a signed certificate are usually similar, but depend to some extent on which CA you get to sign your certificate. Whatever CA you choose, they should have instructions or documentation on how to set up your certificate.
First, you need to create a self-signed certificate using the "keytool" command included with Java (you will need Java installed somewhere on your system and $JAVA_HOME/bin on your PATH):
keytool -genkey -alias tomcat -keyalg RSA -validity 365 -keystore marmosetKeystore
This command will ask you to fill in a bunch of information about your organization. I'm not sure of difference this makes.
This will produce a "keystore" containing all of your keys (currently just the one key you just created) called "marmosetKeystore" stored under the alias "tomcat".
Warning You will be asked to supply a password for the keystore. Use the password "changeit", which is the default passwork used by most of the examples I've seen. I know that this password works, and I have anecdotal evidence that using a different password, or no password at all, will not work. I believe that Tomcat always supplies the password "changeit" by default when it needs to extract keys from a keystore. Note In this document, I refer to the keystore as "marmosetKeystore" and choose "tomcat" for the alias of the key. However, you can pick any names you'd like. Now you need to copy your keystore somplace where Tomcat can find it. To do this, first create the directory Tomcat/conf/ssl (Tomcat/conf should already be there), and copy marmosetKeystore into Tomcat/conf/ssl.
Now you need to configure Tomcat to use your newly create keystore. Find the XML chunk in Tomcat/conf/server.xml that looks like this:
<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25"
maxSpareThreads="75" enableLookups="false"
disableUploadTimeout="true" acceptCount="100"
scheme="https" secure="true" clientAuth="false"
sslProtocol="TLS" />
(You may need to uncomment this block of XML). Add the following line (replace TOMCAT_ROOT with the full path to your Tomcat installation):
keystoreFile="TOMCAT_ROOT/tomcat/conf/ssl/marmosetKeystore"This should yield an XML chunk that looks something like this:
<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25"
maxSpareThreads="75" enableLookups="false"
disableUploadTimeout="true" acceptCount="100"
scheme="https" secure="true"
keystoreFile="/export/homes/submit/tomcat/conf/ssl/marmosetKeystore"
clientAuth="false" sslProtocol="TLS" />
A self-signed certificate will cause most browsers to prompt the user as to whether or not they want to accept a given certificate. However, any client programs that run under Java, such as the BuildServer, will fail when trying to connect over SSL to an entity identified by a self-signed keystore.
To allow a program running under Java to connect an entity identified by a self-signed keystore, you need to export a certificate from the keystore and then import the certificate into the JVM.
To export a certificate from the marmosetKeystore:
keytool -export -keystore marmosetKeystore -alias tomcat -file marmoset.cer
This command will produce marmoset.cer, a certificate that you can import into your JVM so that your Java will trust your self-signed keystore.
To import this certificate into a JVM (assuming that shell variable JAVA_HOME points to your Java installation):
keytool -import -alias tomcat -keystore $JAVA_HOME/jre/lib/security/cacerts -file marmoset.cer
Note The file $JAVA_HOME/jre/lib/security/cacerts is often not writable on unix systems, so you will first need to run: chmod u+w $JAVA_HOME/jre/lib/security/cacerts
before importing the certificate into your JVM.
-
To startup Tomcat:
To shutdown Tomcat:
cd Tomcat/bin
./startup.sh
cd Tomcat/bin ./shutdown.sh
If Tomcat does not start-up properly, Tomcat/logs/catalina.out should tell you why.
The shutdown script doesn't always work; sometimes I have to find and kill the Java process.
Sometimes you'll do everything right to startup Tomcat, but when you try to access a page, you will get a 404 (page not found/not available). If this happens, shutting down tomcat and then restarting it usually fixes the problem.
However, sometimes it's necessary to stop the webapp container and delete the exploded web-archive, like this:
cd Tomcat/bin
./shutdown.sh
/bin/rm -rf ../webapps/submitServer
./startup.sh
where submitServer is the web application we install in Section 6, “Compiling and Installing the Submit Server”.
It is a good idea to install and run tomcat with a normal user account rather than running it as the root user of the unix system.
We set port-forwarding from port 80 to 8080 and from 443 to 8443 so people can access the server using only the protocol (i.e. https) rather than the protocol and the port number. For example, with forwarding from 443 to 8443 enabled, the server can be accessed like this:
https://hostname.cs.umd.edu/
You can delete all the examples in Tomcat/webapps except for the Tomcat/webapps/balancer. These examples show how to write servlets and jsps and are neither a secure nor professional thing to have sitting around.
This is a list of things that have gone wrong with Tomcat for us that you might run into. Note that Tomcat is a large, evolving piece of software with lots of good documentation on the web. If something doesn't work, try googling whatever error message is being generated.
The first place to look is in Tomcat/logs/catalina.out. This file will often contain useful errors that will tell you what the problem is.
Sometimes you need to shutdown and restart Tomcat. I don't know why, but sometimes that works.
In general, Tomcat does a good job of hot-deploying whatever you copy into the Tomcat/webapps directory, and will usually be able to hot-update a webapp that's already running when you copy a new warfile into Tomcat/webapps. But, sometimes Tomcat will not be able to hot-deploy or hot-update, and you'll need to do the following:
Shutdown Tomcat, delete the Tomcat/webapps/submitServer directory, and then restart (sometimes stopping and re-starting again).
You can only define context parameters (context-param) in ONE place at a time, either Tomcat/conf/web.xml or in WEB-INF/web.xml of your warfile. If you put the same parameter in both places, either the webapp will fail to load or Tomcat itself will fail to load.
This is very annoying, it should be possible to over-ride parameters in web.xml. I've written a hacked-up mechanism for doing that that involves defining properties with __override on the end of them and having a special mechanism for doing the lookups in the web.xml file in servlets. Of course this doesn't easily translate to jsps, and in general this is pretty annoying. Such a far cry from POJOs, or anything resembling useful programming...
Return to the directory where you unpacked SubmitServer2 and SubmitServerModelClasses in Section 2, “Unpack Submit Server Components”
Create the ANT properties file
SubmitServer2/local.propertiesand point theproduction.install.locationproperty to your tomcat installation. For example:production.install.location=username@foo.cs.umd.edu:/path/to/tomcator
production.install.location=/path/to/tomcat/on/local/machineNote local.properties is the correct place to put configuration parameters specific to your institution. DO NOT update build.properties directly if you are checking our code out of CVS because build.properties is under CVS control. Note local.properties and build.properties are both read by the build.xml file used by ant. In ant, a property is only set the FIRST time it is read. Any other attempts to set the value of that property are ignored. Thus, because local.properties is read before build.properties, any property set in local.properties will be used instead of a property with the same name in build.properties. -
cd into SubmitServer2 and run this command:
ant production.installThis will find and compile the SubmitServerModelClasses into SubmitServer2, and then produce a SubmitServer2/dist directory with submitServer.war and sharedSubmitServer.jar, and copy those to the appropriate places in the tomcat installation.
The production.install ant task uses "scp" to copy the submitServer.war and sharedSubmitServer.jar files to the appropriate location. It assumes that "scp" is on your path and that you're running Linux. You can always copy the two files produced into the appropriate places: submitServer.war goes into Tomcat/webapps and sharedSubmitServer.jar goes into Tomcat/shared/lib.
You do not need to compile the software with any particular user account or with any special privileges, so long as the generated files can be copied into the Tomcat installation. I always compile Marmoset on my desktop machine with my regular user account and install it into tomcat using a special 'submit' account reserved for running the SubmitServer.
sharedSubmitServer.jar contains some shared code for monitoring the connections with the buildServers. If you don't install it, the only thing that won't work is the BuildServerStatus link available to instructors.
Note Troubleshooting: You can also build the SubmitServer2 project in Eclipse. The project is set up to work in Eclipse with MyEclipse plugin. If you do not have this plugin, ensure that the j2ee.jar is properly linked, by going to Project Properties -- Java Build Path -- Libraries. If j2ee.jar is not in the list, add it by clicking "Add Jars..." and selecting it from SubmitServer2/lib. ![[Important]](important.png)
Important You need to perform this step if you open the project in Eclipse, even if you do not plan to run the ant instruction through Eclipse, because Eclipse automatically builds the files when you open it. When ant sees that the class files are already created, it does not rebuild them. -
To test the submit server, first ensure the tomcat server is
running:
Then go to https://localhost:8443 and log in using the super user account you created in Section 4, “Creating a SuperUser account” .Tomcat/bin/startup.sh