Deployment

Foraging deployment requires command-line interaction. On Windows you can use the built-in cmd, PowerShell or Cygwin. On Mac or Linux, open a terminal window.

Typical deployment workflow

1. Compile / assemble jars with the appropriate configuration parameters
2. 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 the experiment server via java -jar -server server.jar or ant server
4. Start the 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
5. Start a facilitator application by visiting http://www.example.com/foraging/facilitator.jnlp

Required software components

1. A webserver that can deliver Java WebStart (JNLP) files, e.g., IIS, Apache, nginx, Jetty
2. Ant
3. Maven if you want to use the builtin Jetty webserver, this satisfies the first requirement for a webserver if you don't have a webserver set up already.
4. The latest JDK

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 (e.g., Apache, IIS, Jetty, nginx). The JNLP file is how your participant client computers will know where to download the client jars, how to resolve any additional software / 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.

If you don't have an existing webserver, the built-in Maven Jetty webserver is likely your simplest option.

Set up Ant

Ant is needed to compile and deploy the foraging application.

Instructions on how to install Ant on a variety of operating systems can be found on their website 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.

Set up Maven (optional, for the builtin Jetty webserver)

This step is optional and provides convenient access to a webserver. You can install Maven by following the instructions at their website. Once it is installed you should be able to start up a webserver by running

> mvn jetty:run.

Prepare the foraging codebase for deployment

NOTE: WebStart has been officially deprecated and slated for removal in future releases of Java so deployment will be changing soon, see https://github.com/virtualcommons/foraging/issues/43

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 jar file needs to be executed to start the server, and the client and facilitator jars need to be deployed alongside Java WebStart (JNLP) files so that they can be run remotely.

Copy build.properties.example to build.properties and then edit build.properties. The following properties must be set properly for the software to function:

1. sesef.version - this should typically be set to whatever value exists in build.properties.example or unset to use the default declared in the build.xml file.
2. 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.
3. 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 web server, you can leave this at its default value
4. 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.
5. 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 will probably 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 normally available

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 to the right places.

Deploy the foraging software

1. Make sure that your configuration has been copied over to src/main/resources/configuration
2. Run % ant deploy
3. Start the experiment server via % java -server -jar server.jar
4. Start the embedded Maven Jetty web server via % mvn jetty:run
5. Run a facilitator via WebStart by appending facilitator.jnlp to your configured codebase.url. For example, if http://www.example.com/foraging/ was the codebase.url then visiting http://www.example.com/foraging/facilitator.jnlp in your browser would start the facilitator.
6. Run each client by going to codebase.url, e.g., http://www.example.com/foraging/.