The Virtual Commons

building extensible software for collective action research

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.