Implement and operate your experiment

Technical assumptions

• The runtime uses Python 3.11 on Linux. File names are case-sensitive.
• The application receives its PostgreSQL connection through environment variables.
• The container file system is ephemeral. Do not use it to retain data, uploads, or results.
• One instance serves one experiment and supports up to a few hundred simultaneous participants. Report larger or unusual loads early.

Minimum structure

my-experiment/
├── settings.py
├── requirements.txt
├── README.md
├── .gitignore
├── my_app/
│   ├── __init__.py
│   └── ...
├── _static/       # optional
└── _templates/    # optional

Do not nest a second oTree project inside the repository. settings.py must be at its root.

Safe configuration

from os import environ

ADMIN_PASSWORD = environ.get('ADMIN_PASSWORD')
SECRET_KEY = environ.get('SECRET_KEY')

# Keep SESSION_CONFIGS, SESSION_CONFIG_DEFAULTS, and ROOMS here.
# The lab supplies DATABASE_URL at deployment.

• Do not define DATABASE_URL, DEBUG, or AUTH_LEVEL inside settings.py.
• Prefix custom variables with OTREE_, read them with environ.get(), and document their purpose.
• Define ROOMS when the operating flow uses room codes or persistent rooms.

Exact dependencies

otree==6.x.y
psycopg2-binary==2.9.10
# add every other dependency actually used below

Replace 6.x.y with the exact version used in testing. Do not include a Procfile, runtime.txt, or Dockerfile; the server builds the runtime.

Files that must not travel

.venv/
__pycache__/
*.py[cod]
*.sqlite3
.env
.otreezip
.DS_Store
exports/
participant_data/

Exclude local databases, exports, participant data, secrets, virtual environments, caches, and large binaries. Discuss videos or other heavy assets before deployment.

Install and run

python -m venv .venv
# activate the virtual environment on your system
python -m pip install -r requirements.txt
otree devserver

Run automated tests

otree test

Include bots for the main paths and every critical branch. Passing automation does not replace a manual walkthrough.

Test the way it will run

1. Create every SESSION_CONFIG and, where applicable, enter through every Room.
2. Walk through treatments and contingencies in at least two independent browsers or profiles.
3. Verify instructions, payments, timeouts, disconnects, and re-entry.
4. Test planned devices, including phones if the study permits them.
5. Install from a clean clone or ZIP using only the README.
6. Simulate production with OTREE_PRODUCTION=1 and confirm no local data are required.

Source code

• Preferred: a repository URL accessible to the lab team, plus a specific tag or commit.
• Alternative: a complete ZIP shared through a secure institutional channel. Include Git history when needed to identify versions.

Deployment factsheet

1. Build. The lab installs dependencies, configures PostgreSQL, and loads the agreed variables.
2. Correction. If the build fails, the research team supplies a new release; code is not patched without identifying it.
3. Access. The public URL and administrative credential are sent through separate channels.
4. Smoke test. The research team creates a test session, completes each flow, and verifies exports.
5. Release. The service is enabled for the reported dates and load.

Minimum export after every session

• all_apps_wide: integrated longitudinal data across all apps;
• per-app data: exports needed for the study's structure;
• PageTimes: page timing when relevant to quality or diagnosis.

For each release, retain the tag or commit, date, owner, change summary, test results, and database decision.

Implementation checklist