Installation and Maintenance

Installation

For security reasons, BOSS2 should not be run as root or as a normal user. A dedicated user should be created for BOSS2. This can be done with one of the following commands on most Linux or UNIX systems:

$ sudo adduser boss2      # Authentication with sudo

$ su -c 'adduser boss2'   # Authentication with su

MySQL

BOSS2 currently uses MySQL for storing data. Only version 5 has been tested during development.

MySQL should be installed using the method most suitable to your system. On Ubuntu-based Linux distributions, the package required is ‘mysql-server’, on SUSE it is simply ‘mysql’.

BOSS2 will automatically generate the tables required, but the database it connects to will have to be set up before hand. The following is a template for creating a database and user.

1. Connect to MySQL as the root user.

   $ sudo mysql -u root     # Authentication through UNIX username
   
   $ sudo mysql -u root -p  # Authentication through specified password

2. Switch the the MySQL internal database:

   mysql> use mysql;

3. Create the database for BOSS2:

   mysql> create database boss2;

4. Grant user access rights on the database to the user BOSS2 (specifying your own password and noting it down):

   mysql> grant ALL on boss2.* to 'boss2'@'localhost' identified by 'a secure password';

5. Commit the privilege changes to the MySQL server:

   mysql> flush privileges;

6. End your MySQL session:

   mysql> quit;
   

Java

BOSS2 makes heavy use of generics, and therefore requires a virtual machine certificated to run Java 5 software. BOSS2 has been tested with the Sun and IcedTea virtual machines only.

It is recommended to download and install the latest Java version and install it under your BOSS2 user account. The following template should accomplish this on most Linux systems.

1. As your normal user, download the latest Java Development Kit. You want the ‘self-extracting file’ release, with a .bin extension. Save this as /tmp/jdk-install.bin.
2. As your normal user, make the /tmp/jdk-install.bin file world readable and executable.

   $ chmod a+rx /tmp/jdk-install.bin

3. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

4. Switch to the BOSS2 user’s home directory:

   $ cd ~

5. Execute the JDK installer:

   $ /tmp/jdk-install.bin

6. This will have created a JDK directory in your home folder. Take note of the name of this directory! In this case, the directory is called jdk1.6.0_10:

   $ ls -d jdk*
   jdk1.6.0_10

7. Finish your session as the BOSS2 user:

   $ exit

8. As your normal user, delete the JDK installer:

   $ rm /tmp/jdk-install.bin
   

Tomcat

BOSS2 is a distributed as a web application comprising a servlet and all dependencies. BOSS2 has only been tested with the Tomcat servlet container, version 5.5

It is recommended to download and install the latest Tomcat version and install it under your BOSS2 user account. The following template should accomplish this on most Linux systems.

1. As your normal user, download the latest Tomcat. You want the tar.gz release. Save this as /tmp/tomcat.tar.gz.
2. As your normal user, make the /tmp/tomcat.tar.gz file world readable and executable:

   $ chmod a+rx /tmp/tomcat.tar.gz

3. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

4. Switch to the BOSS2 user’s home directory:

   $ cd ~

5. Extract Tomcat:

   $ tar xvzf /tmp/tomcat.tar.gz

6. This will have created a Tomcat directory in your home folder. Take note of the name of this directory! In this case, the directory is called apache-tomcat-6.0.18:

   $ ls -d jdk*
   apache-tomcat-6.0.18

7. Finish your session as the BOSS2 user:

   $ exit

8. As your normal user, delete the JDK installer:

   $ rm /tmp/tomcat.tar.gz
   

Installation

Installation of BOSS2 is performed by extracting the BOSS2.war file into your Tomcat webapps directory. You must then create a directory for BOSS2 to store its resources and tests. The following template should perform this on most Linux systems.

1. As your normal user, download the latest BOSS2.war. Save this as /tmp/BOSS2.war.
2. As your normal user, make the /tmp/BOSS2.war file world readable and executable:

   $ chmod a+rx /tmp/BOSS2.war

3. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

4. Switch to the BOSS2 user’s home directory:

   $ cd ~

5. Enter the Tomcat webapps directory. Replace apache-tomcat-6.0.18 with your Tomcat directory:

   $ ls -d apache-tomcat*
   apache-tomcat-6.0.18
   
   $ cd apache-tomcat-6.0.18/webapps

6. Extract your BOSS2.war file into the webapps directory:

   $ unzip -d BOSS2 /tmp/BOSS2.war

7. This will have created a BOSS2 directory in your webapps directory:

   $ ls -d BOSS2
   BOSS2

8. Switch to the BOSS2 user’s home directory:

   $ cd ~

9. Create directories for BOSS2 to store tests and resources:

   $ mkdir -p storage/testing storage/resource

10. Finish your session as the BOSS2 user:

    $ exit

11. As your normal user, delete the BOSS2.war:

    $ rm /tmp/BOSS2.war
    

Configuration

Editing the web.xml file

To configure BOSS2, you must edit the webapps/BOSS2/WEB-INF/web.xml file to change the parameters for the BOSS2 servlet. The following steps should perform this on most Linux systems.

1. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

2. Switch to the BOSS2 user’s home directory:

   $ cd ~

3. Enter the Tomcat webapps directory. Replace apache-tomcat-6.0.18 with your Tomcat directory:

   $ ls -d apache-tomcat*
   apache-tomcat-6.0.18
   $ cd apache-tomcat-6.0.18/webapps/BOSS2/WEB-INF

4. Edit the web.xml file using your favourite editor.
5. Finish your session as the BOSS2 user:

   $ exit
   

Configuration options

db.host

This specifies the MySQL database host. If you've been following the instructions so far, this will be localhost.

db.db

This specifies the MySQL database. If you've been following the instructions so far, this will be boss2.

db.username

This specifies the MySQL database username. If you've been following the instructions so far, this will be boss2.

db.password

This specifies the MySQL database password. If you've been following the instructions so far you will have noted this.

db.resource_dir

This specifies the resource directory. If you've been following the instructions so far this will be /home/boss2/storage/resource.

test.temp_dir

This specifies the testing temporary directory. If you've been following the instructions so far this will be /home/boss2/storage/testing.

submission.secret_salt

When users upload submissions the security code is generated by hashing the files uploaded, appending a secret salt, and re-hashing the combination. Choose something long and unguessable for this option, and keep it a secret from students!

email.protocol

This sets the protocol that BOSS2 will communicate with the mail host with. Any protocol supported by the javamail framework is supported. The default and easiest option is smtp.

email.host

This sets the email host that BOSS2 will use for sending mail.

email.username

This sets the username used for accessing the email host.

email.password

This sets the password used for accessing the email host.

Maintenence

This section describes some common maintenance tasks that a BOSS2 server administrator may need to perform.

Starting the BOSS2 system

Starting BOSS2 is a case of starting Tomcat. The following steps should do this on most Linux systems if you have followed the installation instructions thus far.

1. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

2. Switch to the BOSS2 user’s home directory:

   $ cd ~

3. Enter the Tomcat bin directory. Replace apache-tomcat-6.0.18 with your Tomcat directory, and note your JDK directory:

   $ ls -d apache-tomcat* jdk*
   apache-tomcat-6.0.18  jdk1.6.0_10
   $ cd apache-tomcat-6.0.18/bin

4. Run the Tomcat launch script, replacing the Java directory shown with the one you noted earlier:

   $ JAVA_HOME=/home/boss2/jvm1.6.0_10 sh startup.sh

5. Finish your session as the BOSS2 user:

   $ exit
   

By default Tomcat, and therefore BOSS2, will be available on port 8080. The address to access would be:

http://localhost:8080/BOSS2/PageDispatcherServlet

Stopping the BOSS2 system

Stopping BOSS2 is a case of stopping Tomcat. The following steps should do this on most Linux systems if you have followed the installation instructions thus far.

1. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

2. Switch to the BOSS2 user’s home directory:

   $ cd ~

3. Enter the Tomcat bin directory. Replace apache-tomcat-6.0.18 with your Tomcat directory, and note your JDK directory:

   $ ls -d apache-tomcat* jdk*
   apache-tomcat-6.0.18  jdk1.6.0_10
   $ cd apache-tomcat-6.0.18/bin

4. Run the Tomcat shutdown script, replacing the java directory shown with the one you noted earlier:

   $ JAVA_HOME=/home/boss2/jvm1.6.0_10 sh shutdown.sh

5. Finish your session as the BOSS2 user:

   $ exit
   

By default Tomcat, and therefore BOSS2, will be available on port 8080. The address to access would be:

http://localhost:8080/BOSS2/PageDispatcherServlet

Backup/Restoration of the Database and Filestore

Backing up and restoring the database and filestore involve getting an SQL dump of the database and backing up the resource directory and placing them back.

Backup procedure

Before backup, you must stop the BOSS2 system as per section Stopping the BOSS2 System. The following template should perform backup on most Linux systems if you have followed the installation procedure above.

1. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

2. Switch to the BOSS2 user’s home directory:

   $ cd ~

3. Create a directory for the backup:

   $ mkdir backup

4. Enter the directory for the backup:

   $ cd backup

5. Dump the MySQL database for the backup using your MySQL BOSS2 password:

   $ mysqldump -u boss2 -p boss2 > boss2.sql
   $ gzip boss2.sql

6. Make a directory to store the resource files:

   $ mkdir resource

7. Copy the resource files into the current directory:

   $ cp /home/boss2/storage/resource/* resource/

8. Return to your home directory:

   $ cd ..

9. Archive the backup (subtitute the date and time as appropriate):

   $ tar cvzf backup.2008-08-17.tar.gz backup/

10. Remove the backup directory to clean up and save space:

    $ rm -r backup/

11. Finish your session as the BOSS2 user:

    $ exit
    

Restore procedure

Before restore, you must stop the BOSS2 system as per section Stopping the BOSS2 System. The following template should perform restoration on most Linux systems if you have followed the installation procedure above.

1. As your normal user, switch to the BOSS2 user account for the rest of these instructions by using one of the following commands:

   $ sudo su boss2 -     # sudo authentication
   
   $ su boss2 -          # su authentication

2. Switch to the BOSS2 user’s home directory:

   $ cd ~

3. Locate the backup you wish to restore:

   $ ls backup.*
   backup.2008-08-17.tar.gz

4. Extract the backup file:

   $ tar xvzf backup.2008-08-17.tar.gz

5. Enter the backup directory:

   $ cd backup

6. Restore the MySQL database for the backup using your MySQL BOSS2 password:

   $ mysql -u boss2 -p boss2 < boss2.sql
   

7. Remove the resource files BOSS2 currently has:

   $ rm /home/boss2/storage/resource/*

8. Restore the resource files in the backup:

   $ cp resource/* /home/boss2/storage/resource/

9. Return to your home directory:

   $ cd ..

10. Remove the backup directory to clean up and save space:

    $ rm -r backup/

11. Finish your session as the BOSS2 user:

    $ exit
    

ADS Import (Warwick-specific)

TBA