Installing TRAKLA2

From SVGWiki

Contents

Software requirements

The following software are required for the Trakla2 server:

  • Trakla2 web environment. A released version of the web environment is available at the Trakla2 research site. For development purposes, the newest version of the system is in the project CVS, which is not public. Some of the previous years' production versions are also stored in the Trakla2 server at HUT.
  • Matrix framework. For development purposes, the newest version is available through project CVS, which is not public. Some of the previous years' production versions are also stored in the Trakla2 server at HUT.
  • Apache httpd web server. The current Trakla2 environment has been tested with httpd 2.2.
  • Tomcat servlet container. The current Trakla2 environment has been tested with version 5.5.
  • Java. Java versions 1.4.x and 1.5.x should work. Java 1.6. does not work with Tapestry 4.0.2.
  • Tapestry Web application development framework. The current Trakla2 environment works with Tapestry version 4.0.2.
  • HiveMind The current Trakla2 environment has been tested with version 1.1.1.
  • j2ee. Required to compile the Trakla2 web environment.
  • Ehcache (version 1.3.0 required. 1.2 does not work.)
  • The Apache implementation of XML-RPC. Other XML-RPC implementations will not work.
  • PostgreSQL database server. There have been no problems with any version of PostgreSQL and (some version of) Trakla2 has been tested on most versions from 7.4 onwards. We recommend using Postgres 8.2 or newer. The PostgreSQL JDBC interface is also required.
  • jcharts. Version 0.7.5 has been tested and works.

NOTE: some of these libararies are downloaded automatically by the install script. See Trakla2 installation for details.

Install Apache and Tomcat

First step in the Trakla2 installation is to install Apache and Tomcat. In most Linux distributions this is easiest to do by using the distribution's own package management system (apt for Debian, yum for Fedora, etc.). If that is not an option, you should download them from http://www.apache.org/ and follow the installation instructions there.

Download and unpack Trakla2

Next, get the Trakla2 web environment, and unpack it to a directory of your choice. For the rest of this document, the root directory of the web environment (for example /home/foo/trakla2) is referred to as $TRAKLA2_HOME.

Install dependencies

Install Java EE

Download Java EE from http://java.sun.com/javaee/downloads/index.jsp and run the installer. It is graphical, so turning on X tunneling when doing this over ssh makes things easier. In order to install Java EE you must have Sun's Java installed and enabled. If not, see configuring software for details on how to enable Sun Java.

Install JUnit

Download JUNIT and follow the instructions described in the JUNIT FAQ. In order for Tapestry to install successfully, you must use JUNIT version 3.8.1. and manually copy junit.3.8.1.jar to /usr/share/ant/lib/. Using other versions causes Tapestry installation to fail, unless you're installing the system as root, which is not recommended.

Download JDBC driver

Download JDBC driver from http://jdbc.postgresql.org/download.html and place it in the directory $TRAKLA2_HOME/libs. If the directory does not exist, create it.

Configure the software

This section contains instructions for configuring each piece of software required for installing Trakla2. For each software $SOFTWARE_HOME refers to the directory where the software has been installed. If, for example, Trakla2 has been installed to /home/user/trakla2, $TRAKLA2_HOME refers to this directory.

In these instructions it is assumed that the software has just been installed to the machine, and no configuration has been done previously. Some or all parts of these instructions may be unnecessary if the software has been installed on the machine already.

These installation instructions currently give specific instructions for installing Trakla2 to a Debian 4 or Fedora 7 system. The exact instructions might not work on other Linux distributions, and won't work on other platforms.

Make sure that you have Sun's Java

Keystore files generated with the Gnu keytool don't seem to work. Therefore, if you have both Sun and Gnu version installed, make sure that you are using the right version by running

update-alternatives --config java
update-alternatives --config javac
update-alternatives --config keytool

If you do not have Sun versions of the tools installed, get it from Sun's pages and install. The tools can be added to alternatives by running

alternatives --install /usr/bin/java java /real/java/executable/dir/java N
alternatives --install /usr/bin/javac javac /real/java/executable/dir/javac N
alternatives --install /usr/bin/keytool keytool /real/java/executable/dir/keytool N

Where N is the priority of the new alternative. Then you can run update-alternatives to set the version you want to use.

Configure SSL

Enable the Apache module:

a2enmod ssl  (in Debian)

In Fedora the ssl module is enabled by default.

Create keys (Debian)

cd /etc/apache2
openssl req -new -x509 -nodes -out server.crt -keyout server.key

Create keys (Fedora)

cd /etc/httpd
openssl req -new -x509 -nodes -out server.crt -keyout server.key

In Debian, add line

Listen 443

to /etc/apache2/ports.conf.

In Fedora, Apache already listens to port 443.

A key for tomcat must be created with the command

keytool -keystore keystore -alias trakla2 -genkey -keyalg RSA

This command will store the new certificate in a file named keystore in the current working directory. The keystore must be stored in a directory that tomcat can read, and it can be stored in, for example, /etc/tomcat.

Integrate Tomcat and Apache with proxy_ajp

Tomcat must be run behind Apache in case you want to use shibboleth login. If you choose to run Tomcat alone without Apache, you can skip this section.

Enable the proxy_ajp module (in Debian)

a2enmod proxy_ajp

In Fedora, proxy_ajp is already enabled.

Edit /etc/apache2/mods-enabled/proxy.conf (in Debian) /etc/httpd/conf/httpd.conf (in Fedora) or and add

   Order deny,allow
   Allow from all

inside the Proxy block.

In Fedora, it would be prudent to also turn ProxyRequests off. To do that modify the httpd.conf by changing

<IfModule mod_proxy.c>
 ProxyRequests On

to

<IfModule mod_proxy.c>
 ProxyRequests Off


Add following lines to $TOMCAT_HOME/conf/server.xml and comment previous entries out:

<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"
              proxyName="localhost"
              proxyPort="443"
              keystoreFile="loctionOfTheKeystoreFile"
              keystorePass="passwordOfTheKeystore" />
<Connector port="8009"
              enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

If you want trakla to be located in the server root, ie. http://trakla.cs.hut.fi/app and not http://trakla.cs.hut.fi/cexer/app, add

<Context path="" docBase="/var/lib/tomcat5.5/webapps/cexer"
   debug="0" privileged="true" allowLinking="true">
</Context>

to $TOMCAT_HOME/conf/server.xml inside the Host element. NOTE: docBase directory can be /var/lib/tomcat5/ or /var/lib/tomcat5.5 or something else depending on version.

Options for developers (Debian)

Developers probably want the application to be deployed automatically without needing to restart Tomcat every time. This can be achieved by adding

CATALINA_OPTS="$CATALINA_OPTS -Dorg.apache.tapestry.disable-caching=true"

to /etc/init.d/tomcat before the line

export CATALINA_HOME CATALINA_BASE CATALINA_OPTS CATALINA_PID JSSE_HOME

and by creating a symbolic link from trakla2/build/cexer.war to $TOMCAT_HOME/webapps/cexer.war

Remote debugging can be enabled by adding

export JAVA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,address=20150,server=y,suspend=n"

to /etc/init.d/tomcat.

Configure Apache

Summary: all traffic to ports 80 (http) and 443 (https) is proxied to 8009 (tomcat via ajp).

Add the following lines to /etc/apache2/sites-enabled/000-default (in Debian) or some appropriate place. If you are not going to run Tomcat behind Apache, you can skip this step.

<VirtualHost *>
       # Proxy all traffic to Tomcat
       ProxyPass / ajp://localhost:8009/
       # Exceptions:
       # ProxyPass /myContent !
       ErrorLog /var/log/apache2/trakla2.log
       # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
       LogLevel warn
       CustomLog /var/log/apache2/access.log combined
       ServerSignature On
       # Uncomment these when using shibboleth
       #<Location />
       #        AuthType shibboleth
       #        ShibRequireSession Off
       #        Require Shibboleth
       #</Location>
</VirtualHost>
<VirtualHost *:443>
       # Proxy all traffic to Tomcat (shouldn't this be 8443?)
       ProxyPass / ajp://localhost:8009/
       # Exceptions:
       # ProxyPass /myContent !
       ErrorLog /var/log/apache2/trakla-ssl.log
       # Possible values include: debug, info, notice, warn, error, crit,
       # alert, emerg.
       LogLevel warn
       CustomLog /var/log/apache2/access.log combined
       ServerSignature On
       SSLEngine on
       SSLCertificateFile    /etc/apache2/server.crt
       SSLCertificateKeyFile /etc/apache2/server.key
       SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
       # Uncomment these when using shibboleth
       #<Location />
       #        AuthType shibboleth
       #        ShibRequireSession Off
       #        Require Shibboleth
       #</Location>
</VirtualHost>

In Fedora add the following lines to /etc/httpd/conf/httpd.conf

ProxyPass / ajp://localhost:8009/
<VirtualHost *>
      # Proxy all traffic to Tomcat
      ErrorLog /var/log/httpd/trakla2.log
      # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
      LogLevel warn
      CustomLog /var/log/httpd/access.log combined
      ServerSignature On
      # Uncomment these when using shibboleth
      #<Location />
      #        AuthType shibboleth
      #        ShibRequireSession Off
      #        Require Shibboleth
      #</Location>
</VirtualHost>
<VirtualHost *:443>
      ErrorLog /var/log/httpd/trakla-ssl.log
      # Possible values include: debug, info, notice, warn, error, crit,
      # alert, emerg.
      LogLevel warn
      CustomLog /var/log/httpd/access.log combined
      ServerSignature On
      SSLEngine on
      SSLCertificateFile    /etc/httpd/server.crt
      SSLCertificateKeyFile /etc/httpd/server.key
      SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
      # Uncomment these when using shibboleth
      #<Location />
      #        AuthType shibboleth
      #        ShibRequireSession Off
      #        Require Shibboleth
      #</Location>
</VirtualHost>

The differences in configuration between Debian and and Fedora are minor: ProxyPass is moved to be outside the <VirtualHost > tags and directories are changed from something/apache2/something to something/httpd/something.

Install Trakla

Decompress trakla2 package.

Copy j2ee.jar, activation.jar and mail.jar from $J2EE_HOME/lib to $TRAKLA2_HOME/libs.

Run the install.sh in $TRAKLA2_HOME.

cd $TRAKLA2_HOME
./install

The installation script takes care of downloading and building most of the dependencies, but in case it fails, the steps are described below.


Install Tapestry

The installation script takes care of this step.

Download Hivemind and Tapestry

wget http://mirror.eunet.fi/apache/tapestry/tapestry-4.0.2.tar.gz
wget http://mirror.eunet.fi/apache/hivemind/hivemind-1.1.1.tar.gz
tar -xf tapestry-4.0.2.tar.gz
tar -xf hivemind-1.1.1.tar.gz

Edit tapestry-4.0.2/config/build.properties:

hivebuild.dir=/pathToHivemind/hivemind-1.1.1/hivebuild

Build tapestry. It will download dependencies automatically. Remember, JUNIT must be installed, or the tapestry installation will fail. It can install JUnit automatically, but only if you are running ant as root.

ant install
ant install  (Yes, it has to be run twice. And be patient with the tests.)

Patch Javassist

The installation script takes care of this step.

Web apps that use Tapestry 4.0 in Tomcat with the security manager enabled fail with a "java.lang.NoClassDefFoundError: org.apache.hivemind.ServiceImplementationFactory" exception.

Perform the patch described in Tapestry issue page, build the javassist jar using ant and copy javassist.jar to $TAPESTRY_HOME/ext-package/lib. If Tapestry was downloaded and installed by Trakla2 installation script, this directory will be $TRAKLA2_HOME/libs/tapestry-4.0.2/ext-package/lib.

Configure Trakla2

The installation script will do most of this part. You must edit the configuration files, but the installation script will open those for you.

  1. Go to directory $TRAKLA2_HOME/code and create subdirectories lib/ and logs/
  2. Go to directory $TRAKLA2_HOME/code/config and copy file specific.properties.base to specific.properties.
  3. Update specific.properties and set the property root.dir to the relative path to $TAPESTRY_HOME.
  4. In the same directory copy log4j.properties.base to log4j.properties
  5. Update log4j.properties and set log4j.appender.A1.file to desired log file (for example $TOMCAT_HOME/logs/cexer.log if using Tomcat)
    1. Notice that if you're using Fedora, the default directory (/var/log/tomcat5.5/) does not exist (corresponding directory is /var/log/tomcat5/)
  6. Copy or link the required jar files to $TRAKLA2_HOME/code/lib
  7. Update $TRAKLA2_HOME/code/src/cexer/Datastorage.properties
    1. set xmlrpc.port to the correct value (default 9876)
    2. set jdbc.driver to the correct value (default org.postgresql.Driver)
    3. set db.url to the correct value (default jdbc:postgresql:trakla2)
    4. set db.username to the correct value (default trakla2)
    5. set db.password to the correct value (no default)
    6. set http.server to the correct value (default trakla.cs.hut.fi)
    7. set https.server to the correct value (default trakla.cs.hut.fi)
    8. set smtp.server to the correct value (default hutcs.cs.hut.fi)
    9. set testcourseid to the correct value (default 100, which must be used if system is restored from original DB)

Configure Tomcat's security policy

In Debian, add the following to /etc/tomcat5.5/policy.d/60trakla.policy

In Fedora, change all instances of tomcat5.5 to tomcat5 and add the following lines to /etc/tomcat5/catalina.policy

grant codeBase "file:/var/lib/tomcat5.5/webapps/cexer/-" {
   permission java.io.FilePermission "/var/log/tomcat5.5/*", "read, write";
   permission java.util.PropertyPermission "*", "read, write";
   permission java.net.SocketPermission "localhost:9876", "listen,resolve";
   permission ognl.OgnlInvokePermission "invoke.*";
   permission java.net.SocketPermission "127.0.0.1:5432", "connect,resolve";
   permission java.lang.RuntimePermission "getProtectionDomain";
   permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
   permission java.lang.RuntimePermission "accessDeclaredMembers";
   permission java.lang.RuntimePermission "getClassLoader";
   permission java.lang.RuntimePermission "setContextClassLoader";
   permission java.lang.RuntimePermission "accessClassInPackage.*";
};
grant codeBase "file:${catalina.base}/webapps/cexer/WEB-INF/lib/-" {
   permission java.io.FilePermission "/var/log/tomcat5.5/*", "read, write";
   permission java.io.FilePermission "/usr/share/java/-", "read";
   permission java.io.FilePermission "/var/lib/tomcat5.5/webapps/cexer/-", "read";
   permission java.io.FilePermission "${java.home}/lib/-", "read";
   permission java.io.FilePermission "${java.home}/../lib/-", "read";
   permission java.io.FilePermission "${java.home}/lib/ext/-", "read";
   permission java.io.FilePermission "${java.home}/jre/lib/ext/-", "read";
   permission ognl.OgnlInvokePermission "invoke.*";
   permission java.util.PropertyPermission "ognl.*", "read";
   permission java.util.PropertyPermission "org.apache.*", "read";
   permission java.util.PropertyPermission "java.class.path", "read";
   permission java.lang.RuntimePermission "createClassLoader";
   permission java.lang.RuntimePermission "getProtectionDomain";
   permission java.lang.RuntimePermission "accessDeclaredMembers";
   permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
   permission java.lang.RuntimePermission "getClassLoader";
   permission java.lang.RuntimePermission "setContextClassLoader";
   permission java.lang.RuntimePermission "accessClassInPackage.*";
   permission java.net.SocketPermission "*", "listen,accept,connect,resolve";
};

In Fedora, edit /etc/tomcat5/tomcat5.conf and /etc/sysconfig/tomcat5 and change JAVA_HOME to correct value.

Configure PostgreSQL

For PostgreSQL installation instructions, see Postgresql documentation.

First, change to user postgres. Such user should be on the computer if Postgresql has been installed.

su
su postgres

Then, reate a database cluster (In Debian, you can skip this step and the next step. Postmaster should already be running.)

initdb -D /database/home/dir (in Fedora /var/lib/pgsql/data is a good choice). 

After the database cluster has been created, you can start Postmaster, the Postgresql daemon

/etc/init.d/postgresql start

(You should also modify the system to set up the postgresql service upon startup.)

Create database user trakla2 with the command

createuser trakla2

You can make trakla2 a database superuser if you want. This might compromise security a bit, but also saves a lot of hassle.

Create database named trakla2 with the command

createdb -O trakla2 -E LATIN1 trakla2

For installation on Mac OS X, see Apples tutorial page.

Database connections use sockets through 127.0.0.1, so add the following to pg_hba.conf ( /etc/postgresql/8.2/main Debian). In Fedora this step is uncenssary, unless you want to use md5 authentication (Fedora uses trust-based authentication on local loopback by default)

host    all         all         127.0.0.1/32          md5

Create a database

Create the tables for the database. The required files can be found in the directory $TRAKLA2_HOME/database.

psql -U trakla2 trakla2 <tables.sql

Add the exercises and exercisedescriptions

psql -U trakla2 trakla2 <exercises.sql

Create a test course and some users

psql -U trakla2 trakla2 <testData.sql

In table appletexercise update the value of column codebase with the command:

UPDATE appletexercise SET codebase='https://new.host.name'

After these modifications the database should be ready to use.

Install Matrix

[TA: Alkuun jotain selitystä, että mikä on Matrix ja mikä on Trakla2 ja miten ne kommunikoivat keskenään.]

Matrix should already have been downloaded and extracted by the Trakla2 installer. If this is not the case, download Matrix from http://www.cs.hut.fi/Research/MatrixPro/ and extract it

unzip MatrixPro-src-1.3.zip

In the following, $MATRIX_HOME refers to the unpacked directory Matrix-1.3

Install Dependencies

Download and unpack version 1.2-b1 of Apache XML-RPC. Copy xmlrpc-1.2-b1.jar and xmlrpc-1.2-b1-applet.jar to $MATRIX_HOME/not-in-release/ext-libs. Version 2.0 of XML-RPC does not work.

Configure the Matrix Framework

Copy $MATRIX_HOME/code/applications/trakla2/server/server.properties.base to server.properties in the same directory

Update server.properties:

  1. set trakla2.server.DATADIR to the desired value (no default)
  2. set trakla2.server.PORT to the desired value (default 1099)
  3. set trakla2.server.FINGERPRINT to desired value (no default)
  4. set trakla2.submissionhandler to the correct value (default applications.trakla2.server.XmlRpcResultClient)
  5. set xmlrpc.server.port to the correct value (default 9876, must match xmlrpc.port in Trakla2 configuration

Build Matrix

Compile matrix

cd $MATRIX_HOME/code
ant trakla2-jar

Build Trakla2

Copy matrix.jar from $MATRIX_HOME/code to $TRAKLA2_HOME/code/context.

> cd $TRAKLA_HOME/code
> ant install

> cp build/cerces.war $TOMCAT_HOME/webapps

Configuring the network

The most important aspect of network configuration is configuring the new server's firewall to accept connections to the Trakla2 server. Since the server machine will be visible to the network outside, it is important to configure the firewalls properly in order to avoid unwanted intrusions.

Firewall configuration

Note: The terminology here refers to the Linux netfilter iptables firewall. If you are using some other firewall software, the terminology may vary. In all command examples it is assumed that the firewall recognizes connection states. If this is not true, you need to use different commands in order to configure the firewall correctly. It is also assumed that the firewall has nat tables enabled. If not, some of the commands given here will not work. And remember, in order to modify iptables, you need root priviledges!

The following firewall ports must accept the following new connections:

  • Port 80 for http
  • Port 443 for https
  • ports 1089, 1099 and 1100 for Trakla2 applets

All established connections should also be accepted. Furthermore, if you do not run Trakla2 using Apache and Tomcat daemons and wish to run it from non-root account (which is preferable), you must open two other ports (typically 8080 and 8443) and preroute traffic from ports 80 and 443 to these ports. This not needed when using Apache and Tomcat.

iptables firewall configuration in detail

Here is a pretty good and detailed example how to set up iptables firewall. In addition to what's detailed there, the following commands should be given. First, in order to enable new connections to a given port, use:

/sbin/iptables -A INPUT -p tcp --dport <port_number> -m state --state NEW -j ACCEPT

Just replace the port number with the desired port.

If you want to preroute traffic from port 80 to 8080 and 443 to 8443 use the following command.

/sbin/iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080

(replace 80 with 443 and 8080 with 8443 in order to reroute https.)

Prerouting is not required if Trakla2 is run under Apache, since Apache runs as a daemon started by the root.

Configuration example

Here's an example configuration script.

#!/bin/sh
sbin/iptables --flush

/sbin/iptables -A INPUT -i lo -j ACCEPT
/sbin/iptables -A OUTPUT -o lo -j ACCEPT

/sbin/iptables --policy INPUT DROP
/sbin/iptables --policy OUTPUT DROP
/sbin/iptables --policy FORWARD DROP

/sbin/iptables -A INPUT -m state --state ESTABLISHED -j ACCEPT
/sbin/iptables -A OUTPUT -m state --state NEW,ESTABLISHED -j ACCEPT

# for ssh
/sbin/iptables -A INPUT -p tcp --dport 22 -m state --state NEW -j ACCEPT
/sbin/iptables -A INPUT -p tcp --dport 80 -m state --state NEW -j ACCEPT
/sbin/iptables -A INPUT -p tcp --dport 443 -m state --state NEW -j ACCEPT
/sbin/iptables -A INPUT -p tcp --dport 1089 -m state --state NEW -j ACCEPT
/sbin/iptables -A INPUT -p tcp --dport 1099 -m state --state NEW -j ACCEPT
/sbin/iptables -A INPUT -p tcp --dport 1100 -m state --state NEW -j ACCEPT

Other configurations that have the same effect are also possible. Use them if the configuration shown here seems weird or is unacceptable to you.

You can test if the configuration works by starting the server and trying to use Trakla2 from another computer. Testing from the local machine doesn't tell if other computers are able to connect to the server.

Running Trakla2

In order to run Trakla2, you must start Apache web server, tomcat, and the Trakla2 RMI-server. Apache and tomcat can be started using the start-up scripts in /etc/init.d/, or using some service configuration tool.

After building Trakla2 and copying a new Trakla2 war to $TOMCAT_HOME/webapps, tomcat may have to be started and then restarted before the system works.

Start the RMI-server

The RMI server can be started using the following commands.

cd $MATRIX_HOME/code
nohup ant run-trakla2 &

Currently there is no ready script for starting the RMI server upon system startup.


Start the Submission Viewer Service

The Submission Viewer can be started using the following commands.

cd $MATRIX_HOME/code
nohup ant run-viewer &

Currently there is no read script for starting the Submission viewer upon system startup.