# Doris Schoolhouse Deployment Notes

## Intended runtime shape on NOMAD

Doris Schoolhouse should run as a standalone NOMAD service from **`/opt/doris-schoolhouse`**.

- **Repo/source path:** `/home/fizzlepoof/repos/truenas-stacks/home/doris-schoolhouse`
- **Live runtime path:** `/opt/doris-schoolhouse`
- **Persistent app data:** `/opt/doris-schoolhouse/data`
- **Published app port:** `8091`
- **Workspace mount for D2L snapshot input:** `/home/fizzlepoof/.openclaw/workspace:/workspace/.openclaw-workspace:ro`

## Important NOMAD networking note

NOMAD does **not** currently have PD's Docker-only external networks (`pangolin`, `ix-databases_shared-databases`).

For NOMAD, Schoolhouse should:
- publish `8091` on the host
- let Pangolin/Newt target the host port externally
- reach shared Postgres on PD over LAN TCP (`10.5.30.6:5432`)
- reach LiteLLM / Qdrant / Paperless / n8n over their existing LAN/public endpoints

## Pre-deploy checklist

1. Copy the repo source into `/opt/doris-schoolhouse`.
2. Create a real `.env` from `.env.nomad.example`.
3. Replace placeholder values for:
   - `SESSION_SECRET`
   - `DATABASE_URL` password
   - `PAPERLESS_API_TOKEN`
4. Ensure the shared Postgres target database/user exist on PD.
5. Apply `app/db/schema.sql` against the `schoolhouse` database.
6. Ensure `/opt/doris-schoolhouse/data` exists and is writable by Docker.
7. Confirm Pangolin/Newt has a resource forwarding `schoolhouse.paccoco.com` to NOMAD host port `8091` if public access is wanted immediately.

## Current live integration status

### Working
- Assignment intake webhook (`/webhook/school/intake/upload`) succeeded in live smoke testing on 2026-05-15.
- Recording workflow (`/webhook/class/upload`) was repaired live on 2026-05-15 and now returns HTTP 200.
- Direct Whisper transcription endpoint on NOMAD succeeded in live smoke testing.
- LiteLLM `medium` on PD succeeded after its Ollama route was fixed.

## Suggested deploy flow

```bash
sudo mkdir -p /opt/doris-schoolhouse/data
sudo rsync -a --delete --exclude '.env' --exclude 'data/' /home/fizzlepoof/repos/truenas-stacks/home/doris-schoolhouse/ /opt/doris-schoolhouse/
cd /opt/doris-schoolhouse
sudo cp .env.nomad.example .env
# edit .env
sudo docker compose --env-file .env config
sudo docker compose --env-file .env up -d --build
```

## Post-deploy verification

```bash
curl -fsS http://127.0.0.1:8091/api/health
curl -fsS http://127.0.0.1:8091/api/health/details
curl -fsS http://127.0.0.1:8091/api/dashboard/summary
```

Then verify:
- D2L snapshot counts load
- assignment intake confirms into n8n/Paperless
- recording conversion works inside container
- recording downstream workflow returns success
- browser uploads return to `/assignments/upload` with a success notice instead of rendering raw JSON
- programming-class uploads create one `source_bundle` submission and immediately queue the Paperless receipt upload

## Serenity backup on NOMAD

If Schoolhouse submission bundles should survive a NOMAD disk problem, back up `/opt/doris-schoolhouse/data` to Serenity.

Current live helper:

```bash
/opt/doris-schoolhouse/bin/backup-to-serenity.sh
```

Behavior:
- mounts Serenity NFS export `10.5.30.5:/mnt/user/data` at `/mnt/serenity-data` when needed
- mirrors `/opt/doris-schoolhouse/data/` into `/mnt/serenity-data/backups/nomad/doris-schoolhouse/data/`
- writes `last_success_utc.txt` and `source_host.txt` markers beside the mirrored data

Suggested cron on NOMAD:

```cron
40 2 * * * /opt/doris-schoolhouse/bin/backup-to-serenity.sh >> /opt/doris-schoolhouse/logs/backup-to-serenity.log 2>&1
```