Engagement Platform Labs: Student Onboarding Guide

Read this before starting Lab 01. The setup splits across hardware, accounts, and one of three operator-console paths. If anything in this guide does not work for you, capture the error output and email drip@errantpacket.com before Day 1.

What you build

Across the 14 labs you assemble an engagement platform from commodity hardware and the Cloudflare developer stack:

A custom OpenWrt sysupgrade image for a GL.iNet Mango router (the drop device), built from upstream packages with ImageBuilder.
An operator console running in your Dev Container or GitHub Codespace, with Tailscale, cloudflared, wrangler, and python pre-installed. A sibling OpenWrt rootfs container is available for parity work.
A two-node Tailscale mesh between the operator console and the Mango, with MagicDNS.
A Cloudflare Tunnel from the operator console to the public internet.
A Cloudflare Worker as the engagement front door (REST API plus ChatOps).
D1 device registry, KV job queue, and R2 artifact storage with auth-gated download URLs (Worker-proxy in class; the take-home doc covers the SigV4-signed-direct-to-R2 variant).
An EmojiChef ChatOps decoder: a food-emoji command arrives as a GitHub issue comment, the Worker decodes and dispatches it, the Mango runs a tcpdump, and an auth-gated R2 download link is posted back as a reply.

The Lab 14 capstone round-trips an emoji command through GitHub issue comments, over the tailnet to the Mango, captures a packet trace, uploads it to R2, and returns an auth-gated download URL as a comment reply.

Hardware kit

Per student:

Item	Purpose
GL.iNet Mango (GL-MT300N-V2)	Drop device. Gets custom firmware in Lab 02.
USB flash drive (16 GB or larger, ext4-formattable)	ExtRoot overlay for the Mango (Lab 03).
Ethernet cable	Connects your laptop to the Mango’s LAN port (the black one).
3.3 V USB-to-UART adapter with dupont leads	Serial console. Required for Lab 01 Steps 6 and 7 (failsafe and U-Boot HTTP recovery).

Bring your own laptop. There is no minimum spec.

The 5 V USB-to-UART adapter you may already own will damage the Mango PCB. Confirm 3.3 V before plugging in.

Required accounts

All free tiers are sufficient.

Cloudflare — your assignment card lists a slot under eplabs.cloud (e.g., 0b38904c.eplabs.cloud) and a scoped CF API token. The instructor pre-creates the DNS records for that slot on the shared parent zone, which has Advanced Certificate Manager enabled so every depth of subdomain (including api.<slot>.eplabs.cloud) gets a TLS cert automatically. You do not need to create a Cloudflare account for the in-class workshop — wrangler will authenticate via the API token on your card. If you want the take-home variant where you manage your own zone on a domain you own, follow handouts/workshop_domain_prerequisites.md.

During Lab 11 you will set two per-student Worker secrets, GITHUB_WEBHOOK_SECRET and GITHUB_TOKEN, using wrangler secret put. Details are in the Lab 11 README; no action required before Day 1.
Tailscale at login.tailscale.com. Create an account. The workshop tailnet auth key is on your assignment card.
GitHub at github.com. A free account can create repositories, generate fine-grained PATs, and configure webhooks. Before Day 1:
- Create or fork your workshop repository (e.g., fork of errantpacket/epl-student-starter).
- Open issue #1 in that repository with a recognizable title such as Workshop command queue. This issue is your persistent ChatOps inbox for the workshop.
Discord (optional, only for the Lab 11 Discord take-home variant; you can complete the full workshop without it). Account at discord.com.

Labs 04 and 05 block without Tailscale and GitHub (and your assignment card with the slot + CF API token). Confirm those before Day 1; the Cloudflare side is provisioned by the instructor — you do not need your own CF account for the in-class path.

Operator console: pick one

The operator console is the Linux shell you use for Day 1 building and Day 2 control-plane work. Pick one of the three paths below. You can switch later.

Option A: GitHub Codespace (zero local install)

The fastest path. Click “Open in Codespaces” on any lab page or visit codespaces.new/errantpacket/epl-student-starter. The free personal Codespaces tier (120 core-hours per month) covers the workshop with headroom; a two-day session uses about 28 core-hours.

No software install on your laptop other than a browser. The cold-start build runs once and takes about 5 minutes; subsequent reattaches are instant.

Option B: Local Dev Container

Run on your own machine. Install:

Docker Desktop (Mac or Windows) or Docker Engine (Linux), or Podman Desktop as a free alternative. Verify with docker ps (or podman ps).
VS Code.
The Dev Containers extension: ms-vscode-remote.remote-containers.

Open the repository in VS Code and pick “Reopen in Container.” First build takes 3 to 5 minutes.

Option C: Minimal local (Lab 01 only)

If you want the lightest on-ramp before committing to a full Dev Container, install Docker (or Podman) only and pull the OpenWrt rootfs image:

docker pull openwrt/rootfs:x86-64-23.05.3

Lab 01’s “OpenWrt sibling” comparison runs from this image. Switch to Option A or B before Lab 04, where the engagement-stack tools (wrangler, Tailscale, cloudflared) become required.

Optional pre-warm (Local Dev Container only)

Pulling the ImageBuilder image and pre-building the operator-console image saves 5 to 10 minutes during Labs 02 and onwards. Skip this if you are using a Codespace; the Codespace warms its own image on first launch.

git clone https://github.com/errantpacket/OpenWRT_Course.git
cd OpenWRT_Course/courses/engagement-platform-labs

# ImageBuilder for the Mango target (~800 MB)
docker pull openwrt/imagebuilder:ramips-mt76x8-23.05.3

# Pre-build the operator-console Docker image
cd labs
make engagement-platform
# Expected: tag epl-engagement-platform:23.05.3 appears in `docker images`.

If the build fails, the most common causes are: Docker daemon not running (docker ps will fail too), insufficient disk space (the build needs about 3 GB free), or a proxy blocking the upstream image pull. Capture the error output for the instructor.

Day 1 labs

Lab	Topic
01	Hardware familiarization. Mango physical inspection, SSH, OpenWrt failsafe, U-Boot HTTP recovery, 3.3 V serial console.
02	Build a custom Mango sysupgrade image with ImageBuilder. Compare against the unconstrained OpenWrt rootfs sibling.
03	ExtRoot. Expand the Mango’s 16 MB flash via USB. Install Tailscale on the overlay.
04	Cloudflare slot verification. DNS records under your slot, `wrangler` auth via your card’s API token, D1 / KV / R2 / Access entitlements visible.
05	Two-node Tailscale mesh between the operator console and the Mango, with MagicDNS and ACL tags.
06	Cloudflare Tunnel. Expose a service from the operator console without port forwarding.
07	First Worker deployment. The engagement front door.

Day 2 labs

Lab	Topic
08	Cloudflare Access. Operator SSO and device service tokens.
09	D1 device registry and audit log.
10	KV job queue and R2 artifact storage with signed URLs.
11	EmojiChef ChatOps. GitHub issue comment to Worker, decode, dispatch via job queue.
12	Drop device deployment. Bake secrets into the Mango image so it self-enrolls on first boot.
13	Edge relay and redirector (Oblique-Relay patterns on the Worker).
14	Capstone end-to-end round-trip.

What to bring on Day 1

Laptop and power adapter.
Hardware kit: Mango, USB drive, Ethernet cable, USB-to-UART adapter (3.3 V).
Your assignment card (handed out at the start of Day 1) — this carries your <slot>.eplabs.cloud domain and a scoped Cloudflare API token; you do not need your own CF account for the in-class path.
Tailscale and GitHub accounts created and confirmed (free tier on both).
GitHub workshop repository created with issue #1 open.
A working operator console: either a Codespace you have already launched once (Option A), or a local Dev Container that opens cleanly (Option B). Verify before you arrive.

Questions

For pre-class and in-workshop questions: drip@errantpacket.com.