5  Deploy DICE yourself

The deployment process, while comprehensive, is designed to be accessible to researchers of all technical backgrounds. The step-by-step instructions that follow are structured to guide users through each stage of the deployment process, regardless of their familiarity with terminal or command-line interfaces. The commands are straightforward, and detailed guidance is provided throughout. It’s worth noting that oTree has been successfully implemented by numerous researchers across various disciplines, many of whom began with limited technical expertise. Importantly, oTree has a large and active user community, which brings several advantages:

  1. Extensive Documentation: oTree is well-documented, with comprehensive guides and tutorials available online.
  2. Community Support: There’s an active forum where you can ask questions and get help from experienced users.
  3. AI Assistance: Because of its popularity and well-documented nature, generative AI tools can provide assistance with oTree-related queries.

The combination of detailed documentation, community resources, and technological support ensures that researchers can efficiently implement their experimental protocols. These resources are designed to facilitate a smooth deployment process, enabling researchers to focus on their experimental objectives rather than technical challenges.

5.1 Prerequisites

Before you begin, ensure you have the following installed:

  1. Python: oTree requires Python 3.7 or higher. Download and install Python from python.org.

  2. pip: This is Python’s package installer. It usually comes with Python installation.

  3. Command Prompt or Terminal: This is a text-based interface to interact with your computer. You’ll use it to run commands for installing and running oTree.

    • On Windows: Search for “Command Prompt” or “PowerShell” in the Start menu.
    • On macOS: Open the “Terminal” application (found in Applications > Utilities).
    • On Linux: You can usually open a terminal with Ctrl+Alt+T or by searching for “Terminal” in your application menu.

5.2 Install oTree

Open a command prompt or terminal and run:

pip install otree

5.3 Extract the Provided oTree Project

Create and open a new directory (e.g. my_DICE_experiment) for your experiment (either manually or using the command prompt or terminal):

mkdir my_DICE_experiment
cd my_DICE_experiment

Now download the DICE.otreezip file (which you can find here) and store it in your new directory. Then use the command prompt or terminal and run the otree unzip command to extract the contents of the otreezip file:

otree unzip DICE.otreezip

If necessary, adjust the path to the otreezip file.

This will unpack the experiment such that you can browse and edit its raw files. One of them is called requirements.txt. You can find it in my_DICE_experiment/ (or whatever name you chose for your project directory). You should have all the requirements installed but it may not hurt to re-install them using:

pip install -r requirements.txt

5.4 Running the experiment locally

Run the following command to set up the database:

otree resetdb

Start the oTree development server:

otree devserver

Open a web browser and go to:

http://localhost:8000

You should see the oTree admin interface.

5.5 Troubleshooting

If you encounter any issues while setting up or running the experiment, consider the following:

  • If you see any “module not found” errors, make sure all required packages are installed.
  • Check that you’re in the correct directory when running commands.
  • Ensure your Python version is compatible with the oTree version used in the provided experiment.
Note

If you encounter any specific errors or issues with the provided experiment, consult oTree’s official documentation, oTree’s official forum, generative AI or Hauke Roggenkamp.

6 Server setup

Note

The following text copies and summarizes oTree’s official documentation.

If you are just testing your app on your personal computer, you can use otree devserver. You don’t need a full server setup.

However, when you want to share your app with an audience, you must use a web server.

Choose which option you need:

  • You want to launch your app to users on the internet: Use Heroku.
  • You want the easiest setup: Again, we recommend Heroku.

6.1 Basic server setup with Heroku

Heroku is a commercial cloud hosting provider. It is the simplest way to deploy oTree.

The Heroku free plan is sufficient for testing your app, but once you are ready to launch a study, you should upgrade to a paid server, which can handle more traffic. However, Heroku is quite inexpensive, because you only pay for the time you actually use it. If you run a study for only 1 day, you can turn off your dynos and addons, and then you only pay 1/30 of the monthly cost. Often this means you can run a study for just a few dollars.

To deploy to Heroku, you should use oTree Hub, which automates your server setup and ensures your server is correctly configured.

oTree Hub also offers error/performance monitoring.

6.1.1 Server performance

Heroku offers different performance tiers for resources such as your dyno and database. What tier you need depends on how much traffic your app will get, and how it is coded.

Performance is a complicated subject since there are many factors that affect performance. oTree Hub’s Pro plan has a “monitor” section that will analyze your logs to identify performance issues.

6.1.2 General tips

  • Upgrade oTree to the latest version
  • With the higher dyno tiers, Heroku provides a “Metrics” tab. Look at “Dyno load”. If users are experiencing slow page load times and your dyno load stays above 1, then you should get a faster dyno. (But don’t run more than 1 web dyno.)
  • If your dyno load stays under 1 but page load times are still slow, the bottleneck might be something else like your Postgres database.