apress/deploy/uno-q/REQUIREMENTS.md

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 (what you'll do) · 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:

   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).