# Manual Heroku Deployment Without oTree Hub

This document explains how to deploy this oTree project to Heroku manually, without using oTree Hub.

## Important Warning

The official oTree documentation recommends deploying to Heroku through oTree Hub because it automates server setup and helps avoid misconfiguration. Manual deployment can work, but it is easier to make mistakes that affect performance, data storage, or launch reliability.

Use this manual route only if the team understands the Heroku setup and will test the deployment before running the live experiment.

Official references:

- oTree Heroku setup: https://otree.readthedocs.io/en/master/server/heroku.html
- Heroku Procfile: https://devcenter.heroku.com/articles/procfile
- Heroku Config Vars: https://devcenter.heroku.com/articles/config-vars
- Heroku Postgres provisioning: https://devcenter.heroku.com/articles/provisioning-heroku-postgres

## What This Project Already Has

The repository already has:

- `Procfile`
- `requirements.txt`
- `settings.py`
- oTree app code

The current `Procfile` is:

```text
web: otree prodserver1of2
worker: otree prodserver2of2
```

This is the expected two-process oTree Heroku setup:

- `web` handles browser traffic.
- `worker` handles background/websocket-related work.

## Prerequisites

Install and log in to:

- Git
- Heroku CLI

Commands:

```bash
heroku login
git --version
heroku --version
```

You also need access to the Heroku team/account where the experiment app will be hosted.

## Step 1: Prepare The Repository

Clone the GitHub repository:

```bash
git clone https://github.com/GoudarziMostafa/KatExperiment.git
cd KatExperiment
```

Make sure the LLM treatment branch has been merged into the branch you want to deploy, or deploy the branch directly.

Check the files:

```bash
ls Procfile requirements.txt settings.py
```

Optional local dependency check:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -c "import settings, base; print('imports ok')"
```

## Step 2: Create The Heroku App

Choose an app name. Heroku app names must be globally unique.

```bash
heroku create YOUR_APP_NAME
```

If the app already exists:

```bash
heroku git:remote -a YOUR_APP_NAME
```

Set the Python buildpack explicitly:

```bash
heroku buildpacks:set heroku/python -a YOUR_APP_NAME
```

## Step 3: Add Heroku Postgres

oTree needs a persistent database on Heroku.

For testing or small pilots, the Essential-0 plan is the smallest current Heroku Postgres plan:

```bash
heroku addons:create heroku-postgresql:essential-0 -a YOUR_APP_NAME
```

For a real launch, choose a database tier that matches the number of participants and expected traffic.

Check that `DATABASE_URL` exists:

```bash
heroku config -a YOUR_APP_NAME
```

Heroku Postgres automatically adds a `DATABASE_URL` config var.

## Step 4: Set Required Config Vars

Set the oTree production/admin settings:

```bash
heroku config:set OTREE_PRODUCTION=1 -a YOUR_APP_NAME
heroku config:set OTREE_ADMIN_PASSWORD="choose-a-strong-password" -a YOUR_APP_NAME
```

Set the OpenAI API key for the new LLM treatments:

```bash
heroku config:set OPENAI_API_KEY="your-openai-api-key" -a YOUR_APP_NAME
```

Optional model override:

```bash
heroku config:set OPENAI_MODEL="gpt-4o-mini" -a YOUR_APP_NAME
```

Do not put `OPENAI_API_KEY` in GitHub, `settings.py`, or any document committed to the repo.

Verify config vars:

```bash
heroku config -a YOUR_APP_NAME
```

## Step 5: Deploy The Code

If deploying from `main`:

```bash
git push heroku main
```

If deploying from another branch, for example `codex/llm-punishment-treatments`:

```bash
git push heroku codex/llm-punishment-treatments:main
```

Watch the build logs. Heroku should install packages from `requirements.txt`, including:

```text
otree==6.0.4
openai>=1.40.0
```

## Step 6: Scale Dynos

Scale one web dyno and one worker dyno:

```bash
heroku ps:scale web=1 worker=1 -a YOUR_APP_NAME
```

Do not run multiple web dynos for oTree unless you have confirmed the deployment is configured for that. The oTree Heroku documentation advises using one web dyno.

Check dyno status:

```bash
heroku ps -a YOUR_APP_NAME
```

## Step 7: Initialize Or Reset The Database

For a new Heroku app before collecting real data:

```bash
heroku run otree resetdb -a YOUR_APP_NAME
```

Warning: `otree resetdb` deletes existing experiment data. Do not run it after collecting real participant data unless the data has been exported and the reset is intentional.

Because this project added new model fields for the LLM treatments, a fresh database reset is recommended before testing the new deployment.

## Step 8: Open The App

Open the deployed app:

```bash
heroku open -a YOUR_APP_NAME
```

Or visit:

```text
https://YOUR_APP_NAME.herokuapp.com
```

Log in to the admin interface with:

- username: `admin`
- password: the value of `OTREE_ADMIN_PASSWORD`

Create test sessions for:

- `AI_judge`
- `humanAI_judge`
- `AI_judge_llm`
- `humanAI_judge_llm`

## Step 9: Verify LLM Behavior

For `AI_judge_llm` and `humanAI_judge_llm`, confirm:

- `OPENAI_API_KEY` is set.
- The app has internet access.
- `openai` installed during build.
- sessions advance past the `AIProcessing` page.
- AI fields appear in data export:
  - `ai_punishment_decision`
  - `ai_punishment_reasoning`
  - `ai_punishment_status`
  - `ai_punishment_fallback_used`

If the API key is missing or the API fails, the app should continue using the old formula and record fallback.

## Step 10: Monitor Logs

During testing:

```bash
heroku logs --tail -a YOUR_APP_NAME
```

Look for:

- build errors,
- database errors,
- missing package errors,
- OpenAI API errors,
- oTree page or live method errors.

## Step 11: Before A Real Experiment

Before launching with real participants:

1. Run a full pilot with the same number of participants as the intended session size.
2. Export test data and confirm the AI fields are recorded.
3. Confirm fallback works by temporarily removing `OPENAI_API_KEY` in a test app.
4. Re-add the key after the fallback test.
5. Reset the database only after confirming no real data must be kept.
6. Confirm Heroku dyno and Postgres plans are adequate for the planned traffic.

## Common Problems

### Build Fails Because `openai` Is Missing

Make sure `requirements.txt` includes:

```text
openai>=1.40.0
```

Then redeploy:

```bash
git push heroku main
```

### App Cannot Connect To Database

Check:

```bash
heroku config:get DATABASE_URL -a YOUR_APP_NAME
heroku addons -a YOUR_APP_NAME
```

If there is no Postgres add-on, create one:

```bash
heroku addons:create heroku-postgresql:essential-0 -a YOUR_APP_NAME
```

### LLM Treatments Always Use Fallback

Check:

```bash
heroku config:get OPENAI_API_KEY -a YOUR_APP_NAME
heroku logs --tail -a YOUR_APP_NAME
```

If `OPENAI_API_KEY` is missing, set it:

```bash
heroku config:set OPENAI_API_KEY="your-openai-api-key" -a YOUR_APP_NAME
```

### Admin Password Does Not Work

Reset the config var:

```bash
heroku config:set OTREE_ADMIN_PASSWORD="new-strong-password" -a YOUR_APP_NAME
```

## Recommended Safer Alternative

If the team is not comfortable maintaining Heroku manually, use oTree Hub for Heroku deployment and then add the OpenAI API key directly in the Heroku app's Config Vars:

```text
OPENAI_API_KEY
OPENAI_MODEL
```

This keeps secrets out of GitHub while still letting the deployed oTree app read them at runtime.