Deploying your experiment to a server

As a response to the Coronavirus crisis, many universities worldwide have closed their doors for some time. Researchers that use experiments as a research method can, therefore, not use university laboratories to conduct their experiments. In this blog post, I discuss an alternative that deploys your experiment to an online server to make it available for online participants. More specifically, I describe how you can use Heroku as a platform to host your oTree experiment and subsequently make it available to your participants online. I focus on oTree as I am most familiar with this software package to program experiments. In the end, I shortly mention an alternative for researchers that use z-Tree.

Setting up Heroku

Heroku is a cloud hosting server that provides a platform for apps, including app management and instant scaling. On Heroku it is free. However, if you run an experiment with a substantial number of participants, you must upgrade to a paid server. As you can immediately scale the server capacity it is not expensive to use. For instance, if you run your experiment in the timeframe of three days, you only pay 3/30th of the monthly fees as you scale it up before you use it and scale it down after you use it. After you have created an account on Heroku, download and install the Heroku Command Line Interface. After installing the Heroku Command Line Interface, there are three ways to deploy experiments to Heroku: oTree Hub, GitHub, and using your command prompt or terminal (for Mac users).

Option 1: oTree Hub

The first option is oTree Hub. Once you have connected oTree Hub with Heroku you can click on "Heroku Server Deployment". At the server deployment you can upload your project. If you set a project up for the first time you need to set up database management. To do so, click on "Configure Add-ons" and enable Heroku Postgres and Heroku Redis, as you don't want to spend money just yet start with the free packages. Now you are ready to go back to oTree Hub, where you can upload an .otreezip file. To create an oTree Zip file go to the path where your oTree project is located and use the command prompt:

cd "[oTree project path]"
otree zip

After running this code in the command prompt, an .otreezip file is created in your oTree project environment (where also your Settings.py file is located). You can upload this .otreezip file to oTree Hub, and oTree Hub will automatically deploy it to the Heroku server. Once you have done so, you can click on "Reset DB". Make sure to save copies of your data because resetting the database will remove all existing data. Your experiment will not be available online at: https://[yourappnamehere].herokuapp.com.

Although oTree Hub is an easy solution it comes at a cost. First, as a non-paying member you can only have two projects, which are both automatically published on oTree Hub. If you want more projects or if you don’t want your code to be published on oTree Hub, you can buy a Standard subscription (8 dollar per month) or a Pro subscription (18 dollar per month).

A screenshot of oTree Hub

Option 2: GitHub

The second option is to integrate Heroku with GitHub. In Heroku, create an app and click on "Deploy". Here, you can authorize Heroku to access your GitHub repositories. After authorizing Heroku, you can search for your GitHub repository and connect it to Heroku. You can either manually deploy your GitHub repository to Heroku or automatically deploy all pushes you make to GitHub. If you add columns (variables in the models.py), you should reset the database in Heroku by using the following code in the Command Prompt.

heroku login
heroku run "otree reset db"

A screenshot of the GitHub integration in Heroku

Option 3: Command Prompt

The third option is to deploy your experiment to Heroku by using your command prompt. In this case, you do not need any third-party software except Heroku. To use the command prompt you need to follow the following steps:

Locate the project root folder (particular oTree instance).

cd "/Users/Name/Folder/"

If you have created a Heroku account, use the following command.

heroku login

If the above command does not work, you probably have not installed Heroku CLI properly. Since you are already in the project root folder you can create the .git here.

git init

Then, you can create a new Heroku-app if you don’t have one yet.

heroku create name_of_your_app
# Or in the case you already created an app you want to edit:
cd myapp

You can push your code locally to Heroku.

git add .
git commit -am "your message here"

Finally push the local repository to the Heroku server.

git push heroku master

If already used, reset the oTree database. Be careful to have saved all the data you need as the oTree database will be empty again.

heroku run "otree resetdb"

In order to view the Heroku app, enter the following command or enter the URL in your browser.

heroku open

Running your Experiment in the Virtual Classroom or on MTurk

Now you have deployed your experiment to the Heroku server you are ready to run the experiment. Go to [your_app_name].herokuapp.com and click on "Sessions" in the header. If you want to run the experiment with students, you can create the session and share the session-wide link through e-mail or other channels. In case you want to run your experiment on Amazon's Mechanical Turk, go to your app in Heroku and hit 'Settings'. Next, go to Config Vars and fill in your AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (both available through MTurk), DATABASE_URL, REDIS_URL (both available through Heroku Add-ons), OTREE_ADMIN_PASSWORD, OTREE_AUTH_LEVEL, and OTREE_PRODUCTION. Once you have done so, you can go back to [your_app_name].herokuapp.com, click on "Sessions", click on the arrow next to "Create Session" and select "For MTurk". Subsequently, you can select the number of participants you want to recruit and publish your hit. Make sure to have enough money in your Amazon's Mechanical Turk account. A huge advantage of oTree is that payments (including bonuses) can be paid automatically through the oTree environment.

A screenshot of the MTurk integration in oTree.

An Alternative for z-Tree

Although I have not much experience with z-Tree, I was made aware that since very recently there is a possibility to install your experiment on a server through z-Tree Unleashed. Hitherto, z-Tree was chained to the stationary configuration in the laboratory and it was not possible to run z-Tree anywhere outside the laboratory. z-Tree Unleashed is a major step forward for z-Tree programmers, however one disadvantage is that you need to run this through your router at home and basically transform this router into a server. Although installation on a server is possible, it requires the use of Debian and for researchers not familiar with Linux this may result in "grave consequences" (sic). As I have no experience using z-Tree Unleashed yet, I look forward to hearing from reseachers that have used it. Please feel free to share your experiences in the comments below.

Final note

When following the steps provided above, you will be able to run your experiment over the internet. I hope this blog post helps researchers to overcome barriers with regard to running experiments outside the lab. In case you have any questions feel free to post them below or contact me directly.