README.md

---
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**
   ```bash
   # 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:

```bash
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:
```bash
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`.