[[PageOutline]]
= GeniusWeb RunServer
This is the homepage of the GeniusWeb run server.

The GeniusWeb main page is [https://tracinsy.ewi.tudelft.nl/trac/Genius2 here].

The run server can run sessions and tournaments as specified.

== Installation
* Install your apache-tomcat 8 installation ​https://tomcat.apache.org/download-80.cgi. You can re-use an existing installation. 
* Download the runserver war file from [http://artifactory.ewi.tudelft.nl/artifactory/webapp/#/artifacts/browse/tree/General/libs-release-local/geniusweb/runserver the artifactory]. Go into the latest version of the runserver and download (right click) the war file. NOTICE: your browser must have cookies enabled to access the artifactory.
* Copy the downloaded war file into the tomcat webapps directory
* (Re)start tomcat 

After (re)starting tomcat your local profilesserver should be up and running.

After installing and starting, go to ​http://localhost:8080/runserver-XXX (replace XXX with the version you installed) to see if it works. 


== Running a Session
To run a session using the new-session GUI :

* Go to ​http://localhost:8080/runserver-XXX and click on "new session".
* enter a valid profilesserver URL in the domain/profile server field
* enter a valid partiesserver URL in the parties server field
* Inside the Participants area, select the party and profile for the first party and click add
* Repeat that until all parties have been added.
* Press the "Start Session" button.

[[Image(https://tracinsy.ewi.tudelft.nl/trac/Genius2RunServer/raw-attachment/wiki/WikiStart/snap.png, 90%)]]

The information made available about the running session is determined by the protocol. For SAOP, there are currently two ways to check the progress on the running session
* Check the output of the tomcat web server (eg in catalina.out)
* Check the log files written by the protocol. 


Usually progress is not directly available because this information could be abused by the negotiating parties.


== Run a Tournament
To run a tournament using the new-tournament GUI :

* Go to ​http://localhost:8080/runserver and click on "new tournament".
* Select N: the number of parties in each session. 
* enter a valid profilesserver URL in the domain/profile server field
* enter a valid partiesserver URL in the parties server field
* Inside the Profiles area, select a profile in the Profile combobox and click add
* Repeat the last step until all needed profiles have been added. Give at least N profiles
* Inside the Parties area, select a party in the Party combobox and click add
* Repeat that until all parties have been added. Give at least N parties
* Press the "Start Tournament" button.

[[Image(https://tracinsy.ewi.tudelft.nl/trac/Genius2RunServer/raw-attachment/wiki/WikiStart/runtour.png, 60%)]]

== The source code
You can read the source code through the "Browse source" button at the top of this page. You can check out the source code through svn with
{{{
svn checkout https://tracinsy.ewi.tudelft.nl/svn/Genius2RunServer/
}}}



= Communication protocol

TODO clarify what is MUST

This section deals with the communication protocols with the runserver. These may be relevant when you need to communicate directly with it, e.g. when you build your own GUI or start up your own sessions and tournaments from a script. Other implementations of a runserver should adhere to the same communication protocols to ensure compatibility with GeniusWeb. 

=== Run Negotiation 
This section describes the [source:/src/main/java/geniusweb/runserver/RunNego.java RunNego] service. It is available at {{{http:..:8080//runserver/run}}}.
This service starts up and runs a complete Nego (session or tournament) when it is accessed (http get or post).
To start a negotiation, the http get must include a JSON-serialized [https://tracinsy.ewi.tudelft.nl/trac/Genius2/browser/protocol/src/main/java/geniusweb/protocol/NegoSettings.java geniusweb.protocol.NegoSettings] object. All details are in the javadocs, here we discuss it only briefly.

After session is started, popup shows the negotiation ID. The ID starts with the name of the protocol (SAOP, APP) followed by a serial number.

Typically the settings looks like this (session with SAOP protocol):
{{{
{"SAOPSettings": {
    "participants":[
        {"party":"http://party1","profile":"ws://profile1"},
        {"party":"http://party2","profile":"ws://profile2"}],
    "deadline":{"deadlinetime":{"millis":100}}
}}
}}}

The "SAOPSettings" indicates that these settings are SAOPSettings and (see Settings.getProtocol) will be interpreted by the SAOP protocol.


The participants is a list with PartyWithProfile items: a "party" field containing a http address on a partiesserver, and a "profile" field containing a websocket address on a profilesserver.

The deadline contains the deadline for the SAOP, which is how long the negotiation can last.

To run a tournament, the NegoSettings typically look like this:
{{{
{"AllPermutationsSettings":{
 "parties":["http://server/../party1","http://server/../party2"],
 "profiles":["ws://server/../profile1","ws://server/../profile2","ws://server/../profile3"],
 "reuseParties":false,
 "partiesPerSession":2,
 "sessionsettings":{"SAOPSettings":{"participants":[],"deadline":{"deadlinetime":{"millis":10}}}}}}
}}}


The parties is a list of party URIs, just like in the session settings 

The profiles is a list of profile URIs, just like in the session settings

If reuseParties is set to to false, parties are drawn from the list without return. If it is set to true, parties are drawn with return (meaning all parties can occur multiple times in each session)

partiesPerSession sets the number of parties (and matching profiles) for each session. Profiles are always drawn without return (never appear twice in a session)

sessionsettings contains basically all the normal run-sessionsettings. This is used as a "template" for all sessions of the tournament. You can put any use any session setting here, and each session will be run according to the protocol you select here. In the example we use the SAOP protocol which takes participants and deadline as arguments, as discussed above. The participants list this time is empty, the AllPermutationsProtocol adds the the required parties to this list. So if you provide a non-empty list here, then these parties would be present in every session in the tournament.


=== View Running Negotiations
The websocket address {{{ws:..runserver/websocket/running}}} sends updates of the current list of running negotiations. The list is sent as a JSON List of strings, each string being the negotiation ID of the running session.  Every time the list changes, a new complete list is sent to clients listening to the websocket.

== Viewing the outcome of a negotiation
Logs are available through {{{http:..:8080//runserver/log}}}. The filenames are the Negotiation IDs (shown in the popup after starting a negotiation) extended with ".json". 

A log file usually is created only after the negotiation (session or tournament) completed. Protocols may opt to write these more frequently but since these logs are public they could be abused by parties, to see what their opponents are doing.


== Using the source code ==
You can download the source repository of rhe java implementation. Note that you don't need this if you just want to use the run server to run sessions or tournaments.

{{{
svn checkout https://tracinsy.ewi.tudelft.nl/svn/GeniusWebRunServer/
}}}

Since this is a tomcat web application, you need Eclipse Enterprise edition if you want to run this from Eclipse. 
Also, to checkout from Eclipse, you need to prepare Eclipse for this. Check https://tracinsy.ewi.tudelft.nl/trac/GeniusWeb

It is maven based so you only need maven to compile the code.