# Interactive lab — how it works (creators & students)

## Short answer

**Today:** Students can start a **shared Fly template VM** (e.g. `registry.fly.io/htb-lab-test:latest`) in the browser. The **Docker zip upload** is mainly for **download + run locally** — it does **not** automatically replace the Fly image when you upload or “clear” a zip.

**Product direction (not fully built yet):** Generic in-browser lab while authoring → after zip is reviewed and built to Fly, students get **that** image. That handoff is **manual** today (deploy zip → paste image tag).

---

## Who can do what (today’s code)

| Action | Who |
|--------|-----|
| **Download lab zip** | Everyone |
| **Run docker locally + submit flag** | Everyone (if they have the flag) |
| **Start in-browser Fly VM** | Anyone with **≥1 CPE** (“fuel”) on each new session |
| **Start VM without fuel debit** | Staff: `joshua.goossen@gmail.com`, `admin-test@hackthenbuild.com`, or Auth `app_metadata.role=admin` / `is_admin=true` |
| **Official episode labs free for 2 weeks** | **Not implemented** yet |
| **“Fuel carrier” role** | **Not implemented** yet — only raw `profiles.total_cpe` + staff bypass |

Debate page shows a short **Browser lab vs download** note on hack challenges.

---

## Two separate paths (do not mix them up)

| Path | What the student gets | What the creator configures |
|------|------------------------|-----------------------------|
| **A. Interactive lab (Fly)** | Browser session on a Fly Machine (terminal + app ports) | **Lab Configuration** panel: `image`, services, duration → saved as `challenges.lab_config` |
| **B. Download lab (zip)** | `.zip` with Dockerfile / compose → run on their laptop | **Docker File Upload** widget → stored URL on the challenge |

Path **A** does **not** read the zip at “Start Lab” time.  
Path **B** does **not** start Fly.

---

## What “Test This Lab” does today

1. Creator (or student) clicks **Start Lab**.
2. Site calls `/api/lab/start` with `lab_config` from the panel (or from the published challenge).
3. Vercel asks Fly to start a Machine from **`lab_config.image`** (default: shared template `htb-lab-test`).
4. Session is stored in **`lab_sessions`**; UI polls until the VM is up. Session length is **5–60 minutes** (author chooses; platform enforces the cap).

So **Test This Lab** = preview of path **A** using whatever image tag is in the box — usually the **generic** template until you change it.

---

## What Docker zip upload does today

1. Creator uploads a zip in the **Docker File Upload** widget (scanner / storage).
2. On publish, students get a **download link** on the challenge page.
3. Students run `docker compose up` (or similar) **on their own machine**.

**Not automated today:**

- Upload zip → auto-build on Fly → auto-update `lab_config.image`
- “Clearance” or moderation flipping from generic VM to custom VM

Reference code for a future **zip → fly deploy → image tag** pipeline lives under `fly/builder-service/` and `fly/server.reference.js` — **not** wired to production builder yet.

---

## Intended creator workflow (today, manual)

### While building the challenge

1. Leave **Fly.io image tag** as the template (e.g. `registry.fly.io/htb-lab-test:latest`).
2. Use **Test This Lab** to verify Fly + Vercel + Supabase (`lab_sessions`) work.
3. Upload **Docker zip** for the download path; test zip locally yourself.

### When your custom lab is ready for students in the browser

1. Build and deploy **your** image to Fly (`fly deploy` from your zip, or internal builder when available).
2. Copy the registry tag (e.g. `registry.fly.io/htb-lab-test:deployment-…`).
3. Paste it into **Fly.io image tag** in Lab Configuration.
4. **Publish** the challenge (`lab_config` is saved on the challenge row).
5. Students’ **Start Lab** then uses **your** image, not only the generic template.

Until step 1–4 are done, students still get the **generic** template if they use Start Lab — even if the zip is already uploaded for download.

---

## Intended creator workflow (future — if we automate)

1. Creator uploads zip → scan/clearance queue.
2. After approval, platform builds image to Fly (builder service).
3. `lab_config.image` is updated automatically.
4. **Test This Lab** and student **Start Lab** use the custom image without pasting tags.

That matches: *“generic VM until their Docker is submitted and cleared.”*  
**Status:** aspirational; implement builder-service integration + moderation hooks to get there.

---

## Student-facing copy (suggested)

**Interactive lab**

> Start a temporary lab environment in your browser (uses our cloud VM). Uses 1 fuel · session time limit applies.  
> For the downloadable Docker version of this challenge, use the zip below and run it locally.

**Download only**

> Download the lab zip and run it on your machine with Docker. The in-browser lab is not available for this challenge until the author enables it.

---

## Ops checklist

- Vercel: `FLY_API_TOKEN`, `FLY_APP_NAME`, Supabase service role  
- Supabase: migration `20260519190000_lab_sessions_and_lab_config.sql`  
- Fly: template image deployed (`fly/` → `htb-lab-test`)  
- See [lab-test-checklist.md](./lab-test-checklist.md)