The Virtual Commons

building extensible software for collective action research

foraging

Foraging Experiment Deployment

Typical workflow

On the server side:

  1. Compile / assemble jars with the appropriate configuration parameters set
  2. Deploy / copy jars and JNLP files to a location on the filesystem that is mounted on a webserver (e.g., accessible from the web).
  3. Start up an experiment server via
    java -jar -server server.jar

    or

    ant server

Start up client software on each client computer by opening a browser to the URL associated with the client.jnlp and client.jar files, e.g., http://www.example.com/foraging/client.jnlp

Start up a facilitator application by visiting http://www.example.com/foraging/facilitator.jnlp

Currently, foraging deployment requires the command-line. On Windows you'll need to use the built-in cmd shell or a more advanced shell environment like Cygwin or Windows PowerShell. On Linux or Mac OS X, just open up a terminal (Terminal.app on the Mac).

One item on our wishlist would be a graphical installer / deployment dashboard - if you'd like to help, please let us know!

Required software

  1. A webserver with the mime-type set properly for delivering Java WebStart (JNLP) files
  2. Ant
  3. Maven if you want to use the built-in Jetty webserver. This satisfies the first requirement for a webserver.
  4. Java JDK 1.6
You must have the Java Development Kit (JDK) installed, and not just the Java Runtime Environment (JRE)

Setting up a webserver

The client software is distributed using Java WebStart, and the JNLP files for the client and facilitator need to be delivered by some kind of a webserver (examples include Apache, Lighttpd, IIS, or any servlet container like Tomcat, Resin, or Jetty). The JNLP file is how Java on the client side knows where to download the client jars, where to resolve any additional jar dependencies, and which class contains the main method / entry-point to the application. If you have an existing webserver set up keep in mind that you may need to configure your webserver to properly deliver JNLP files by adding a mime-type entry associating application/x-java-jnlp-file with the jnlp file extension.

Using the built-in Maven webserver
If you'd like to skip the maintenance hassle of installing and configuring your own webserver, just use the built-in Maven Jetty webserver. You will need to install Maven, however.

Step 1 - Install the Java 1.6 JDK

You must make sure that the Java 1.6 JDK is installed properly. This means that you should have javac and java on your path. If you installed the JDK in a special location, make a note of it, because you will need it to set up Ant properly. In order to function properly, Ant needs the JAVA_HOME environment variable to point to the location where you installed Java. In Linux this might be /usr/java/latest, or /opt/jdk or wherever you decided to install the JDK. In Windows this is usually C:\Program Files\Java\jdk1.6.0_10 or something along those lines.

Step 2 - Set up Ant

Ant is currently needed to properly compile and deploy the foraging application.

Instructions on how to install Ant on a variety of operating systems are detailed here but the basic steps are to:

  1. download the binary distribution of Ant
  2. unpack it somewhere (and keep track of its location!). On Linux this might be /opt/ant or /usr/local/ant or /usr/share/ant, on Windows it is wherever you decide to install it. We recommend a location like C:\tools\ant
  3. set the JAVA_HOME and ANT_HOME environment variables to point to the appropriate locations. The deploy.bat file in the foraging directory can be used as a template to deploy the software on Windows, just change the paths of ANT_HOME and JAVA_HOME to reflect your system's configuration.
  4. set the PATH variable to include the bin directories under JAVA_HOME and ANT_HOME so you have access to the ant executable.

Step 3 - Set up Maven (required to run the builtin Jetty webserver)

This step is optional if you have an existing webserver, but provides convenient access to a webserver if you don't. The process for installing Maven is much the same as installing Ant. The Maven downloads page has some instructions on how to do this, which involves downloading and unpacking the Maven archive somewhere and then setting the M2_HOME environment variable and PATH variable to provide access to the mvn executable. Just as in the Ant instructions you will need to make the bin directory under M2_HOME part of the PATH so that you have access to the mvn executable. For Windows installations, there is a convenience jetty.bat included that does most of the work, you just have to tell it where you installed Maven by setting M2_HOME to that location.

Step 4 - Download the foraging software

  1. Download the latest stable release of the foraging package from BitBucket
  2. Unpack the source archive and then enter the unpacked foraging directory (e.g., cd foraging-0.2)

Step 5 - Prepare the foraging software for deployment

The foraging software consists of a set of jarfiles and JNLP files. There is a server jar, a client jar, and a facilitator jar. The server jarfile needs to be executed to start the server, but the client and facilitator jars need to be deployed alongside Java WebStart (JNLP) files so that they can be run remotely. Follow these steps to install the software properly on your system:

  1. copy build.properties.example to build.properties and then edit build.properties.
    Attention
    The following properties must be set properly or deployment will not work.
    1. server.address - the server name, set this to the IP address or domain name of the machine that will be running the experiment server and hosting the webserver. Due to Java's security model, the same machine must perform both these tasks.
    2. web.dir - an absolute path on the server's filesystem that specifies where you would like to deploy the foraging jars and JNLP files. Note that it must be accessible / mounted by the webserver.
      If you are using the builtin Maven Jetty webserver, you can leave this at its default value
    3. codebase.url - the URL that maps to the above path. If you want to use foraging as the project name, you can get by with just setting the server.url and commenting this line out, since the build.xml that loads this properties file sets the codebase url to the server.url + /foraging by default.
    4. server.port - the port you want the Java experiment server (located in server.jar) to listen on - this must be a free, unused port on your system and you may need to poke a hole in your firewall to allow traffic to go through. The experiment server is the Java server process handling all the various client requests like moving around, harvesting a resource, and, in general, executing the game logic. By default it is 16001, which is usually unused (hopefully - if conflicts occur we can change this default).
  2. After editing the build.properties file and saving it, you can run ant help to see if the deployment values are sane. After you've made sure that files will be copied into the right place, execute ant deploy and everything should get copied over appropriately.

Step 6 - Deploy the foraging software

  1. Make sure you have configured your experiment properly.
  2. Copy all the configuration files (e.g., server.xml, round0.xml, round1.xml, round2.xml, ...) into src/main/resources/configuration
  3. Run ant deploy to install the software.
  4. To run the server, try executing java -server -jar server.jar
    If this command does not work, use ant server instead
  5. If you want to run the embedded Maven Jetty webserver, execute mvn jetty:run in a shell.
  6. You should now be able to run the facilitator via WebStart by going to whatever value you used for codebase.url and adding a /facilitator.jnlp to the end of it. For example, if I use http://www.example.com/foraging/ as my codebase.url then I would go to http://www.example.com/foraging/facilitator.jnlp to start the facilitator.
  7. Clients can be started by going to codebase.url directly, an index.html file that redirects to client.jnlp should be installed there. Using the same example as earlier, we can start a client by visiting http://www.example.com/foraging/

Limitations and Known Issues

At the moment the experiment server and the webserver must be resident on the same machine due to restrictions from the Java security model - it should be possible to circumvent this issue by modifying the security manager but it would require some time to research and then implement.

Foraging Experiment Configuration

There are a number of configuration parameters you can use to tweak the runtime behavior of the foraging experiment. In order to modify an experimental treatment you will have to perform the following steps:

  1. Make sure your foraging/src/main/resources/configuration directory contains the appropriate server.xml and round*.xml files. This directory must contain at minimum a server.xml file and its referenced round*.xml, e.g., round0.xml, round1.xml and round2.xml. There are samples used from experiments run at Arizona State University and Indiana University stored in foraging/src/main/resources/configuration/asu-experiments and foraging/src/main/resources/configuration/indiana-experiments. If you end up losing or corrupting the configuration files, you can always copy that set of configuration files from one of these directories to start off as a sample by executing something like cp foraging/src/main/resources/configuration/asu-experiments/* foraging/src/main/resources/configuration/.
  2. Modify the round*.xml files as needed to tweak or change any of the parameters listed below.
  3. Modify build.properties as necessary according to the Foraging Deployment instructions.
  4. Run ant deploy from the top-level foraging directory where the build.xml file resides - see Foraging Deployment for more information about deployment.
Parameter Name Allowed Values Description
chat-enabled true / false Enables/disables a communication round before the beginning of this round.
chat-duration 0 - N Duration of the communication round, in seconds.
chat-instructions text/html Rudimentary HTML or text to be displayed when the user is given the opportunity to chat.
sanction-type real-time / post-round / none The type of sanctioning allowed. When set to real-time, participants are allowed to sanction each other during the round. When set to post-round, participants may only sanction at the end of the round and are presented with a table allowing them to choose how many tokens to reduce from each other participant. Make sure to also specify the sanction-cost and sanction-penalty parameters (these default to 1:2, respectively, so it costs a participant one token to reduce another participant's tokens by 2).
practice-round true / false Enables/disables the practice round. In the practice round, participants will be able to reset the resource distribution, but do not receive any income from the tokens they collect.
clients-per-group 1 - N If set to a number > 1, participants are placed partitioned into groups consisting of N participants each. Each group has a resource distribution, and all participants in each group share that resource distribution in an open-access setting.
regrowth-rate float between 0 - 1 The regrowth rate is the multiplier / scaling factor used to adjust the probability that the current cell generates a new token. It is multiplied by the neighboring tokens ratio to generate a minimum threshold probability.
max-cell-occupancy integer between 1-N The maximum cell occupancy represents the number of participants that can occupy a given cell. If set to 1, then only one participant can occupy a cell at a time. If set to N, then N participants can all occupy the same cell.
display-group-tokens true / false Enables/disables the group token display that shows the current tokens for all members of the group at the top of the screen.
quiz true / false Enables/disables a quiz for this round, which causes the server to block until all quizzes have been submitted.
quiz-instructions text/html The instructions to be displayed for the quiz, should contain the form and input fields as well. Input fields in the form should named q1, q2, q3, ... qn so that the quiz questions can be correlated with their answers. The answers to the quiz questions should be created in a similar format, i.e., for the given example, there should also be q1, q2, q3, ... qn configuration parameters.
always-explicit true / false Enables / disables whether or not explicit mode is always on.
duration 0 - N Duration of the round, in seconds.
resource-width 0 - N The width of the resource grid.
resource-depth 0 - N The depth of the resource grid (in the 2D of the foraging experiment, this is the height).
private-property true / false Enables / disables single participant per resource grid, typically used for the practice round only.

Foraging Documentation

Before you start

We've migrated our old documentation from our wiki to this website. If you still encounter any broken links here please let us know.

First, make sure you've followed these steps to make sure you have the appropriate environment set up to install and run the foraging software. In order to deploy and run the foraging software you'll need:

  1. JDK 1.6 or better
  2. Ant
  3. (optional) Maven if you want to use the built-in Jetty webserver

Setting up the software

  1. Download the foraging codebase and unzip it on the server you wish to use to run the experiment. The foraging experiment server can be run on Windows, Linux, or Mac.
  2. Configure the foraging experiment
  3. Deploy the foraging experiment onto your server

Running the software

After a successful deployment, there are three components to the foraging software that need to be run, in order:

  1. The experiment server can be started on your server machine via java -jar -server server.jar or ant server
  2. Start up one facilitator application via Java WebStart by opening a browser to http://example.com/foraging/facilitator.jnlp (where example.com should be replaced with your server machine's URL). The facilitator application is used by the person running the experiment to monitor and drive the experiment workflow.
  3. Start up client applications on each and every client machine that will be participating in the experiment. For example, our typical foraging experiments run with 10-20 participants, partitioned into groups of 5. So in our case, we'd start the client application on either 10, 15, or 20 workstations, depending on how many participants we had. You can start up a client application via Java WebStart similar to the facilitator application by opening a browser to http://example.com/foraging/. You should see a general instructions / waiting room message on each client screen.

After all clients and the facilitator have successfully connected to the server, return to the facilitator interface and click on the Round -> Show Instructions menu item to send the first round's instructions to each client interface. You should see every connected client's interface change to display the instructions for the practice round. If the images in those instructions don't display properly, there is a problem with the webserver / deployment configuration.

At this point the experiment won't begin even if you click on Experiment -> Start or Round -> Start because the server is waiting for all the clients to submit their quizzes. If you want to skip this step, you can tell the server to skip the quizzes by going to the terminal window where you started the experiment server and typing skip-quiz and hitting enter. At this point you should be able to start the actual experiment round.

After a round ends, each client interface will be automatically shown a debriefing page that displays their current earnings and that of their group. After this has been displayed you'll click on Round -> Show Instructions to display the next round's instructions to each client, and after you're ready to begin the next round you'll either click on Round -> Start to start a regular round or Round -> Start Chat to start a chat round. If you'd like to stop a round prematurely, you can hit Round -> Stop at anytime.

Experiment Data

The raw data saved from the experiment is stored in a directory relative to where you are running the experiment server, in the experiment-data directory. The files themselves are stored in directories following a month-day-year/time-of-experiment-run format. You can use the ant convert target to generate various plaintext csv files and statistics for analyzing the experiments. By default the convert target looks in a raw-data directory relative to the root of the codebase. You can change this by passing in a savefile.dir property which should point at a directory containing the month-day-year/time-of-experiment-run subdirectories. We'll be working to make this process a little smoother eventually. A typical workflow that we use for processing data is:

  1. Run an experiment
  2. Copy experiment data from experiment-data to /data/foraging/raw
    alllee% cp -rp experiment-data/* /data/foraging/raw
    alllee% l /data/foraging/raw
    total 40
    drwxrwsr-x 10 alllee alllee 4096 2010-04-15 16:06 ./
    drwxrwsr-x  7 alllee alllee 4096 2010-08-05 17:41 ../
    drwxrwsr-x  4 alllee alllee 4096 2010-03-22 12:44 03-10-2010/
    drwxrwsr-x  4 alllee alllee 4096 2010-03-22 12:45 03-11-2010/
    drwxrwx---  5 alllee alllee 4096 2010-03-31 15:19 03-31-2010/
    drwxrwx---  3 alllee alllee 4096 2010-04-01 11:34 04-01-2010/
    drwxrwxr-x  4 alllee alllee 4096 2010-04-06 15:51 04-06-2010/
    drwxrwx---  4 alllee alllee 4096 2010-04-15 14:28 04-07-2010/
    drwxrwx---  4 alllee alllee 4096 2010-04-14 13:32 04-14-2010/
    drwxrwx---  5 alllee alllee 4096 2010-04-15 14:25 04-15-2010/
    
  3. Run ant convert -Dsavefile.dir=/data/foraging/raw to convert all the data at /data/foraging/raw
  4. Run rsync -avzP /data/foraging/raw --exclude "*.save" --exclude "*.xml" /data/foraging/processed to copy over all the generated CSV text files into the /data/foraging/processed directory.
Syndicate content