oTree¶
Operating System:
Terminal:
Shell:
Editor:
Package Manager:
Programming Language:
Database:
Utility:
Extension:
Operating System:
Terminal:
Shell:
Editor:
Package Manager:
Programming Language:
Database:
Utility:
Extension:
Operating System:
Terminal:
Shell:
Editor:
Package Manager:
Programming Language:
Database:
oTree is a framework based on Python which allows to build:
multiplayer strategy games (e.g. prisoner’s dilemma, public goods game, and auctions);
controlled behavioral experiments in economics, psychology, and related fields;
surveys and quizzes.
oTree 5 is based on oTree Lite, a new implementation of oTree that runs as a self-contained framework, not dependent on Django.
For more information, check here and here.
Initialization¶
For information on how to use the Additional dependencies parameter, please refer to the Initialization: Bash Script and Initialization: PyPI Packages section of the documentation.
Production Server¶
In order to use oTree in production, it is necessary to run the production server, via the otree prodserver command, by selecting the option prodserver.
In addition, it is necessary to use the Input Folder parameter, and select the directory with the source code, namely the directory which contains the oTree file settings.py.
While starting oTree with the prodserver option, by default the application start a PostgreSQL database server. The Postgres user is ucloud, the default password is ucloud, and the name of the accessible database is otree_db.
The local PostgresSQL database connection string is:
DATABASE_URL=postgres://ucloud:ucloud@localhost/otree_db
Additional parameters¶
The user can select one or more optional parameters when starting the job, e.g.:
PRODUCTION mode set to 1 enables PRODUCTION mode (default is 0 for DEBUG mode)
AUTH LEVEL set to "STUDY" enables restricted access (default is "DEMO")
ADMIN password allows to change the password (by default the oTree username is admin and the password is admin-password)
Postgres database allows to select an existing PostgreSQL data dir.
Important
To be shared with an audience, the app needs to be deployed with a public link.
Database dumps¶
It is possible to back up the oTree PostgreSQL database. This functionality is controlled with two optional parameters:
Database dump frequency: The backup feature is enabled by setting this parameter (disabled by default). The parameter value sets the number of minutes between consecutive dumps (and between the job start and the first dump).
Database dump directory: Folder where the database dumps should be saved. If no folder is mounted, database dumps are saved in
/work/db_dumps.
Note
Database dump files are named using the timestamp of the dump as <yyyymmdd>_<hhmmss>_dump.out.
Restoring a database dump¶
The database can be restored from a dump using a PostgreSQL Server job.
Start a PostgreSQL Server job with an empty folder mounted to Database path, and the folder containing the database dump file mounted using the Add folder parameter.
When the job starts, open the job's terminal window and run:
$ psql -f /path/to/dumpfile postgres
Note
Replace /path/to/dumpfile with the path to the actual .out that the database should be restored from.
Depending on the size of the database, restoring can take a while to finish.
The restored database will be saved in the mounted Database path and can be used as Postgres database when starting the oTree app.
Important
When restoring a database from a dump file, be sure to use a version of PostgreSQL Server the closest possible to the version present in oTree (where the restored database will be used).
Development Mode¶
If the user want to test/develop the oTree app, she/he can select the Development mode parameter. In development mode, the user can edit the application files via the terminal interface and test the application before production.
From terminal it is possible to visualize all the oTree command options, by digiting:
$ otree --help
Creating a new oTree project¶
A new oTree project can be created via command line by writing:
$ otree startproject project_name
In addition a new app can be created by entering the project and writing:
$ otree startapp app_name
Start a development server¶
Once the oTree project/application is ready, it is possible to start from the terminal a development server, by first deleting the db.sqlite3 database and then writing:
$ nginx & otree devserver
It is then possible to open the interface.
The server can be started also from a *.otreezip format file via the command
$ nginx & otree zipserver file.otreezip
oTree Lite does not support certain features present in projects developed with older oTree version.
To check, it is possible to run otree update_my_code, which will highlights the necessary changes to make, before to
run the code on oTree Lite.
Note
When the server is started with devserver or zipserver, SQLite database is used.
Important
Do not start a production server from the terminal. In order to use oTree in production, it is necessary to start the job by selecting the prodserver option. Only in this way the PostgreSQL database is persistent, it is saved on UCloud and can be used for future instances.
Creating an archive¶
It is possible to zip the otree project into an archive, by entering the project folder, and write
$ otree zip
The archive will be created within the project.
Automated Testing¶
Tests of a project app can be launched by adding use_browser_bots=True to the corresponding session configuration in the project settings.py file.
In case, for example, of the demo project (created by using the otree startproject command),
enable automatic testing for the guess_two_thirds app as follow:
from os import environ
SESSION_CONFIGS = [
dict(
name='guess_two_thirds',
display_name="Guess 2/3 of the Average",
app_sequence=['guess_two_thirds', 'payment_info'],
num_demo_participants=3,
use_browser_bots=True,
),
dict(
name='survey', app_sequence=['survey', 'payment_info'], num_demo_participants=1
),
]
Examples of how to define tests.py files can be find here.
In the example above it is necessary to add the files tests.py present in guess_two_thirds and payment_info.
From terminal it is then possible to use the command:
$ otree test name_of_the_session
in this case the name of the session is guess_two_thirds
or
otree test name_of_the_session --export dir_name
where the --export flag is added to export the data generated by the bots to a CSV file stored in the specified folder, dir_name.
In order to simulate the app in a more realistic way, instead of using the otree test --export command, one can run the server and create a session.
The pages will auto-play with
browser bots once the start links are accessed.
Note
For oTree<5 the string to add to the setting file is 'use_browser_bots': True.
Contents