README.md

metadata

title: oTree Production Server
emoji: 🎯
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: 0.0.1
app_file: Dockerfile
pinned: false

oTree HF Production Template

This directory packages the IBE public policy oTree demos for deployment on a Hugging Face Space using the Docker runtime. It was cloned from otree-projects/ibe-pp and augmented with container and deployment assets.

Directory Overview

• Dockerfile – builds the production image expected by Hugging Face Spaces.
• docker-entrypoint.sh – runtime bootstrap that ensures SQLite initialization, collects static files, and launches the ASGI server.
• requirements.txt – locked dependencies for the production image.
• .dockerignore – keeps dev artifacts (db.sqlite3, logs, caches) out of the build context.
• settings.py, apps/, tests/ – unchanged oTree project source.

Deploying to a Hugging Face Space

1. Create the Space

   • Runtime: Docker.
   • Visibility: choose Private or Public per your needs.

2. Add secrets / environment variables (Settings → Repository secrets):

   Key	Purpose	Example
   OTREE_ADMIN_PASSWORD	Protects the oTree admin interface	set-a-unique-password
   OTREE_AUTH_LEVEL	Optional access control (STUDY, DEMO, BASELINE)	STUDY
   OTREE_DATABASE_URL	Override DB (defaults to SQLite under /data)	postgres://user:pass@host:5432/dbname

   Additional variables such as SENTRY_DSN, OTREE_SECRET_KEY, or mail settings can also be defined here.

3. Populate the repository

   # from repository root
   cd otree-projects/hf-prod-ibe-pp
   git init  # if pushing standalone
   git add .
   git commit -m "Initial oTree HF deployment"
   git remote add origin https://huggingface.co/spaces/<org>/<space-name>
   git push origin main
   

4. Space build & launch

   • Hugging Face automatically builds the Docker image.

• The container starts /app/entrypoint.sh, which:
  • Creates the SQLite database (default: /tmp/otree.sqlite3) if OTREE_DATABASE_URL/DATABASE_URL points to SQLite.
  • Launches otree prodserver1of2 0.0.0.0:$PORT (HF sets $PORT).
• The app becomes available at https://<org>-<space-name>.hf.space/.

Local Verification

To build and run the same image locally before pushing:

cd otree-projects/hf-prod-ibe-pp
DOCKER_BUILDKIT=1 docker build -t ibe-pp-hf .
docker run --rm -p 8000:8000 \
  -e OTREE_ADMIN_PASSWORD=changeme \
  -e OTREE_AUTH_LEVEL=STUDY \
  ibe-pp-hf
# open http://localhost:8000/

For persistence, mount a volume:

docker run --rm -p 8000:8000 \
  -v $(pwd)/data:/data \
  -e OTREE_ADMIN_PASSWORD=changeme \
  ibe-pp-hf

Notes & Customization

• Database: The default fallback sqlite:////tmp/otree.sqlite3 is ephemeral. Configure an external Postgres database (e.g., Neon, Supabase) via OTREE_DATABASE_URL (or DATABASE_URL) for any session data you need to persist across restarts.
• Static assets: For lightweight deployments the built-in static files under _static/ are served directly by oTree; add an external asset pipeline only if required.
• Session configs: Update settings.py or add new apps as usual; rebuild the Space to apply changes.
• Logging / monitoring: Set SENTRY_DSN, OTREE_PRODUCTION=1 (already set), or add custom logging handlers as desired.

Once pushed, you can administer the server via https://<space-url>/otree/admin using the password stored in OTREE_ADMIN_PASSWORD.