Deploy an oTree application

Deploy multiplayer experiments and surveys with oTree and PostgreSQL

oTree is a Python framework for multiplayer experiments, behavioural research and surveys. This guide creates a current oTree project, stores its data in PostgreSQL and runs its production server on Clever Cloud.

Prerequisites

• A Clever Cloud account
• Git
• uv
• Clever Tools, installed and connected to your account

Create an oTree project

Generate a project with the latest oTree release and move into its directory. The command asks whether you want to include the sample games:

uvx otree startproject oTreeExample
cd oTreeExample

The generated requirements.txt declares oTree and its PostgreSQL driver. Initialise the Git repository, then create a Python application with a local alias:

git init
clever create -t python -a myOTreeApp

Clever Tools targets your personal organisation by default. To use another organisation, add --org ORGANISATION or -o ORGANISATION when you create or link the application.

You can display your application’s URL or add a custom domain. A custom domain also requires DNS configuration:

clever domain
clever domain add your.website.tld

Create the PostgreSQL database

Create a PostgreSQL add-on and link it to the application:

clever addon create postgresql-addon myOTreeDb -p xxs_sml -l myOTreeApp

oTree expects its connection string in DATABASE_URL, while a linked Clever Cloud PostgreSQL add-on provides POSTGRESQL_ADDON_URI. Add a run.sh file at the project root to map the variable before starting oTree on the Python runtime’s backend port:

#!/bin/bash

export DATABASE_URL="${POSTGRESQL_ADDON_URI}"
otree prodserver 9000

Configure oTree

Enable production mode, protect the administration interface and configure the startup script:

clever env set OTREE_PRODUCTION 1
clever env set OTREE_AUTH_LEVEL DEMO
clever env set OTREE_ADMIN_PASSWORD "$(openssl rand -base64 32)"
clever env set CC_RUN_COMMAND "bash run.sh"

DEMO leaves public demonstrations accessible while protecting the administration interface. Use STUDY when participants must only access experiments through links you provide. The default administrator username is admin; replace the generated password with a value you can store securely if you need to log in.

Deploy the application

Commit the project and deploy it:

git add .
git commit -m "First deploy"

clever deploy
clever open

The oTree home page redirects to the public demo list when you included sample games. PostgreSQL preserves sessions, participant data and configuration across restarts and deployments.

Learn more