Omar SobhandClaude Opus 4.8
48b88b0f0d
Student pre-workshop checklist for the confirmed model: each team runs the Docker stack locally + board over USB, everything localhost, board auto-connects (no code, no accounts). Lists the board-laptop prereqs (Docker, adb, git, disk, pre-fetched bundle), the on-the-day flow, a pre-flight self-check, and an instructor checklist for the remaining decisions. Co-Authored-By: Claude Opus 4.8 <[email protected]>
103 lines
5.2 KiB
Markdown
103 lines
5.2 KiB
Markdown
# APESS 2026 Workshop — Laptop Prerequisites
|
||
|
||
**"Design the Agent Your Building Deserves" · 27 July · a 5-hour build session.**
|
||
Do these **before you arrive** so we spend the session building, not installing.
|
||
|
||
> Companion docs: [`WORKSHOP-FLOW.md`](./WORKSHOP-FLOW.md) (what you'll do) ·
|
||
> [`ONBOARDING.md`](./ONBOARDING.md) (how the board comes up).
|
||
|
||
---
|
||
|
||
## How it runs (so the prerequisites make sense)
|
||
Each team runs the **whole platform on its own laptop** — a small Docker stack (web + API) that
|
||
comes up with **one command**. Your **Arduino Uno Q** plugs into that same laptop over **USB**.
|
||
Everything is **localhost**: the browser, the API, and the board all talk on your machine. Once
|
||
the stack is up and the board is plugged in, it **auto-connects to your team — no codes, no
|
||
accounts, nothing over the network.** (WiFi isn't used during the workshop; it's only for a future
|
||
step that registers boards with our production cloud.)
|
||
|
||
So each team needs **one "board laptop"** with a few things pre-installed. Extra teammates just
|
||
need a browser pointed at that laptop.
|
||
|
||
---
|
||
|
||
## TL;DR
|
||
- **Board laptop:** install **Docker**, **adb**, and **git**; pull the workshop bundle ahead of time.
|
||
- **Everyone else:** a modern browser is enough.
|
||
- **No accounts, no API keys** — the AI cloud access is baked into the board app.
|
||
|
||
---
|
||
|
||
## What the workshop provides (do NOT install)
|
||
- **Arduino Uno Q (4 GB)** board + **USB-C cable** — one per team.
|
||
- **ADXL355 accelerometer(s)** + wiring — the FabLab kit.
|
||
- **Cloud AI access** — baked into the board app. **No Anthropic/Claude account needed.**
|
||
- The **web app** itself (you run it locally from the bundle below).
|
||
|
||
---
|
||
|
||
## The team "board laptop" — pre-install these (large downloads, do them at home)
|
||
1. **Docker** — Docker Desktop (macOS/Windows) or Docker Engine + Compose (Linux).
|
||
Verify: `docker run hello-world` succeeds.
|
||
2. **adb** (Android platform-tools) — the USB bridge to the board.
|
||
Verify: `adb version` prints a version. (macOS: `brew install android-platform-tools`.)
|
||
3. **git** — to fetch the workshop bundle. Verify: `git --version`.
|
||
4. **~10 GB free disk** — Docker images (web + API) + the board's App Lab base image (~0.9 GB).
|
||
5. **The workshop bundle, pre-fetched** so you're not downloading on the WiFi at 14:00:
|
||
```sh
|
||
git clone <workshop-repo-url> # [instructor: final repo/bundle URL]
|
||
cd <repo>/deploy/lan
|
||
docker compose up -d --build # pre-build the images once, at home
|
||
docker compose down # then stop until the day
|
||
```
|
||
(Also pre-pull the App Lab base image on the board — it's fetched on first Run.)
|
||
|
||
## Everyone else on the team
|
||
- A **current browser** (Chrome/Edge recommended; Firefox works). That's it — you'll open the board
|
||
laptop's local URL.
|
||
|
||
---
|
||
|
||
## What you'll do on the day (no accounts, no claim codes)
|
||
1. **Bring the stack up:** `cd deploy/lan && docker compose up -d` → open **`http://localhost:8090/`**.
|
||
2. **Get the board app:** in Team Registration, click **Download the board app** (served by your own
|
||
stack), then on the Uno Q: **App Lab → Import an app → pick the zip → Run.** `[instructor: confirm the App Lab access flow for the room]`
|
||
3. **Attach the board:** plug the Uno Q into the board laptop over USB and run
|
||
**`./deploy/lan/connect-board.sh`** (or `--watch` to keep it auto-attaching).
|
||
4. **It just connects:** type your team name and the board **auto-binds to your team** — no code.
|
||
Unplug/replug is handled automatically; a **Disconnect / Reconnect** control is there if you need it.
|
||
5. **Build:** walk Modules 1–3, submit your Agent Design Document.
|
||
|
||
---
|
||
|
||
## Pre-flight self-check (before you travel)
|
||
- [ ] **(Board laptop)** `docker run hello-world` works.
|
||
- [ ] **(Board laptop)** `adb version` and `git --version` work.
|
||
- [ ] **(Board laptop)** Ran `docker compose up -d --build` once (images built) and opened `localhost:8090`.
|
||
- [ ] Laptop charged + charger packed (5-hour session).
|
||
- [ ] A current browser.
|
||
|
||
---
|
||
|
||
## No accounts to create
|
||
- ❌ No Anthropic / Claude account or API key — the cloud key is baked into the board app.
|
||
- ❌ No claim codes — in this local USB setup the board auto-connects.
|
||
- ✅ Everything is localhost; nothing depends on the room WiFi.
|
||
|
||
---
|
||
|
||
## Notes for the curious (why these specific tools)
|
||
- **Docker** runs the web + API stack in one command, identically on every laptop.
|
||
- **adb** carries the board over USB; the API (in a container) reaches it via `host.docker.internal`.
|
||
- The web runs on **`:8090`** (not `:8080`) because `:8080` is the board's own port, forwarded over adb.
|
||
|
||
---
|
||
|
||
## Instructor checklist (finalize before publishing to students)
|
||
- [ ] **The workshop bundle URL** (git repo or a downloadable archive) students clone/pull.
|
||
- [ ] **Pre-built image distribution** — consider publishing `apess-web`/`apess-api` to a registry (or a
|
||
USB `docker load` bundle) so teams `docker compose up` without a source build on the day.
|
||
- [ ] **Exact Arduino App Lab access** on the Uno Q for the room (and whether it needs any login).
|
||
- [ ] **Pre-seed** the ~0.9 GB App Lab base image locally so 9 teams don't each pull it live.
|
||
- [ ] Decide whether `connect-board.sh --watch` runs via a small launchd/systemd unit (hands-free re-plug).
|