drpaulbrewer/eeps repository overview

2020-Sep-07

⁠What is this?

This is Paul Brewer's fork of an open source system originally developed at and for Caltech, called Marketscape, that ran their double-auction based economics experiments in the early 2000s at the "EEPS" lab founded by Prof. Charles R. Plott.

It is posted here for testing purposes only, and is not in fully working order.

This software has been changed from the original to try to run it on docker.

Issues with this fork should not be seen as indicative of the original software.

Marketscape had been previously released as open source (GPL) under a grant from the Gordon and Betty Moore Foundation, but no longer seems to be distributed from http://marketscape.caltech.edu⁠. The software was originally developed in the mid-late 1990s, and so is now 20+ years old (with an update around 2007-2010 and a week or so spent with docker around 2015). Other laboratories have since released other software (e.g. oTree) for human-subject double auction market experiments.

The age and current condition of this fork is a good reason not to use it. The recent social and government interest in tightening privacy regulation is another reason not to use this software fork. The purpose of the software -- after all -- is to collect data on human trading behavior, in a university laboratory setting. Whether running this software in docker in a university computer lab or another location (such as a researcher's home) satisfies privacy regulation requirements is left as an exercise to YOU the USER. Also several of the instruction pages as well as the links to http://marketscape.caltech.edu⁠ are no longer valid.

As with most open source software, this docker container fork is provided with NO WARRANTY and ALL RISK is borne by the USER, which is YOU if you use docker to run this container.

The purpose of this fork was to explore the feasibility of running that software on docker.

The following procedure shows some promise, but has not been thoroughly tested and the software has a number of html pages that require updating.

⁠To Run

The software requires 2 docker containers to run -- a mysql container for the database and this eeps container for the experiment.

1. Create a local docker network so the mysql database and eeps have a way to talk to each other.

docker create network my-net

1. Start a mysql database container. Note that version 5 is required (an old version). This starts a mysql database with an empty root password, which is not safe if left exposed to the open internet. However, it should be only accessible from the docker host. The eeps software expects there to be no root password on the database.

docker run --name mysql --network my-net -e MYSQL_ALLOW_EMPTY_PASSWORD=1 -p 127.0.0.1:3306:3306 -d mysql:5

1. Start the eeps container. The following command configures it for usage only from the docker host. For usage from other computers, replace 127.0.0.1 with the host's ip address and replace 8888 with 80.

docker run --name eeps --network my-net -p 127.0.0.1:8888:80 -d drpaulbrewer/eeps

1. Point a web browser to http://127.0.0.1:8888/marketscape⁠

Select the "v2" configuration link to configure and run an experiment.

1. After configuring and starting an experiment from the configuration tool, take note of the url and prepend http://127.0.0.1:8888/⁠ or http://your-ip-address/⁠

2. End the experiment by finding and running the stop.perl script.

⁠Extracting the Data

1. Find the scripts to stop the experiment and capture results. This will have to be done with docker exec

Get the first 4 digits of the container's hex code from docker ps -a

docker exec -it <hex code goes here> bash
# this will log you in as root in the container
# cd ~exp/marketscape
# ls
200907-cf-demo-robot  inst  param.err  param.out  setup  src  (hint: the experiment directory is the directory with the date in the name)
# cd 200907-cf-demo-robot
# ls
cgi-bin  commands  conf  config  data  environ  market  params  personal_html  public_html  result-0900  result.perl  start.sh  startserver.perl  stop.perl  syslog.perl  tt
# ./stop.perl stop stop please stop
... wait for it to stop the experiment ...
# ./result.perl
... is supposed to send the results to /usbdrive/marketscape/result ... but there are issues
# cd /usbdrive/marketscape/result
# ls
200907-cf-demo-robot-result-0900.zip  bank.log     bnk_log.awk   invhist2.html  marketcol.rtf       marketlog2csv.py  recent_X.gif    result.perl  trades_X.gif
README.rtf                            bankcol.rtf  invhist.html  market.log     marketlog2csv.perl  mb2.awk           recent_all.gif  trades.csv   trades_all.gif
... note: some files were empty... others had to be regenerated by looking in result.perl for the commands that were supposed to run but did not succeed ...

You can copy out the usbdrive result directory with the docker cp command

docker cp <hex code for container>:/usbdrive/marketscape/result/ result

• If that looks complicated and not ready for most users, that's pretty much true.
• If you want some extra assurance, you should probably create a copy of the MySQL database running in the mysql container. mysqldump is the tool for this.
• An earlier version of this software automatically sent a copy of any data after the experiment by email to [email protected] or some similar address overseen by the EEPS Lab. I think it still tries to do that but doesn't have mail server access so it fails.