EWTeam Client Guide
===========================

OVERVIEW
--------
The EWTeam Client project provides a web-based Team Client which interfaces to
a PC^2 Server without the need to install the PC^2 Team module on a team machine.
Contest teams use a standard web browser to access web services which in turn
link to an installed PC^2 Server.  The EWTeam Client provides all the services
normally provided by the standard PC^2 Team Client, EXCEPT:
  --it does not support the "Test Run" facility.
  --it does not support sending Clarifications to ALL teams (Clarifications can
      be sent to any individual team, just not to all teams at once).
      
NOTE: the EWTeam project is intended to be used by CONTEST ADMINISTRATORS 
to support the ability of teams to participate in a contest using just a web browser. 
It only needs to be installed at the site HOSTING the contest; it is not necessary 
for TEAMS to install anything -- all a team needs to do is obtain the contest URL 
from the Contest Administrator and then use any web browser to connect to the contest as a team.      

The EWTeam Client project was implemented by a Computer Science Senior Project
Team at Eastern Washington University under the direction of Professor Tom Capaul.

The remainder of this document presumes basic familiarity with using the PC^2
system to configure and run a contest.  See the PC^2 Contest Administrator's
Guide under "Documentation" at the PC^2 Home Page (http://pc2.ecs.csus.edu) for
details. 


DEPENDENCIES
------------
In order to use the EWTeam Client, it is necessary for teams to have access to 
a web server running PHP (the installation process, below, includes inserting 
PHP modules into the web server for access by the browser).


PC^2 SETUP
----------
Before attempting to setup and use the EWTeam Client, you should install and 
configure a complete PC^2 system.  This includes downloading the PC^2 code, 
starting a PC^2 Server, starting a PC^2 Admin and using it to configure the 
contest, and starting one or more PC^2 Judges.  See the PC^2 Administrator's 
Guide for details. Note that the PC^2 installation does not need to be on the
same machine as the web server which will support the EWTeam Client. 

  IMPORTANT NOTE:  the EWTeam Client requires using PC^2 version 9.3 Build 2696
    (or higher).   

  IMPORTANT NOTE:  In order to support the EWTeam Client, the PC^2 configuration 
must include a scoreboard account explicitly named "scoreboard2".  This 
account is used by the EWTeam Client to access current contest standings for the
team display. Be sure to create this special account when setting up contest 
accounts using the "Generate Accounts" function in the PC^2 Admin.  

The "scoreboard2" account SHOULD NOT BE USED FOR ANY OTHER FUNCTION THAN 
SUPPORTING THE EWTEAM CLIENT.  If you plan to run your own "PC^2 Scoreboard", 
use the default PC^2 Scoreboard Account "scoreboard1", or some other account; do
not use the "scoreboard2" account for any functions within PC^2 as this will 
conflict with operation of both the EWTeam Client and with the PC^2 scoreboard.


INSTALLING THE EWTEAM CLIENT
----------------------------
1. Determine the document root directory on your web server (on our Linux
Apache2 server it was /var/www, for example).
 
2. Create a directory named "pc2team" beneath the web server document root.

3. Copy the contents of the EWTeam Client "dist" directory (index.html, Team/,
Login/, uploads/ and lib/) into the pc2team directory beneath the document root.

4. Edit the pc2v9.ini file in the EWTeam "lib/" directory (not the pc2v9.ini 
file in your PC^2 system) as follows: 
  (a) in the [client] section, replace "localhost" with the hostname (or IP 
    address) of your PC^2 server. This allows the EWTeam Client to know where to 
    find the PC^2 Server.
  (b) in the [client] section, add an entry of the form
       scoreboard2password=xxxx
    where xxxx is the password you assigned to the "scoreboard2" account in the
    PC^2 Administrator (see the previous section).  This allows the EWTeam 
    Client to login to the server to obtain contest standings.


STARTING THE EWTeam CLIENT SERVICES
-----------------------------------
To start the EWTeam Client web services, go to the "lib/" directory of the EWTeam 
installation (under the pc2team directory of the web server) and run the 
PC2JavaServer.jar using the command:

      java -Xmx1600M -jar PC2JavaServer.jar
      
This starts the Java "bridge" which manages connections between the web server
and the PC^2 Server.  At this point teams should be able to open a browser 
window pointing to the Team Client.  The URL which teams should use will be the
URL of your web server, with "pc2team" appended.
 

TROUBLESHOOTING
---------------

--If you are having trouble submitting files and/or clarifications, check the
permissions on the "uploads" folder under the pc2team folder on the web server.
This folder must all allow write permission to the web server. 
(For example, when a team submits a run the submitted file is copied into 
the "uploads" directory; this folder needs to be writable.)

--The EWTeam Client has a limit on the size of source files which may be 
submitted; currently that limit is 512K.  (This value can be 
changed by editing the file submitProblem.php.)

--The EWTeam Client relies on having an up-to-date PHP5 module in the web server.
If your PHP module is old it may cause problems; try updating it.  
We have tested with PHP5 on an Ubuntu server; the command to install this on 
Ubuntu is
     sudo apt-get install libapache2-mod-php5
     
--The current EWTeam Client implementation has several places where error 
diagnostics are displayed on the Java console (the console where PC2JavaServer.jar
was run) rather than being forwarded back to the team web page.  If you are 
having trouble figuring out why something isn't working, be sure to look at the
Java console for additional hints.



$Id: SETUP.txt 93 2014-03-22 20:46:39Z clevengr $
