onlyn00bs-badge

docker.md (3931B)

---

 # Docker: reproducible build environment
 
 Spin up the firmware build toolchain on any machine without installing
 PlatformIO, the pioarduino platform, or the xtensa toolchain by hand. The
 [`Dockerfile`](../Dockerfile) at the repo root bakes all of that in, pinned, so
 a build on your laptop and a build in CI produce the same artifacts.
 
 > **Scope:** this containerizes **building**. It does **not** containerize
 > flashing or provisioning — those touch host hardware (USB serial, Bluetooth)
 > that Docker Desktop can't reach on macOS/Windows. See *Flashing* below.
 
 ## What's pinned
 
 | Layer | Pin | Where |
 |---|---|---|
 | PlatformIO Core | `6.1.19` | `ARG PLATFORMIO_VERSION` in the Dockerfile (matches the dev machine) |
 | Arduino platform | pioarduino `55.03.38` (core 3.x / IDF 5.x) | `[core3x]` in `firmware/platformio.ini` |
 | Base image | `python:3.13-slim` | Dockerfile |
 | Libs | NimBLE-Arduino `^2.1.0`, U8g2 `^2.35.30` | `firmware/platformio.ini` |
 
 The image build **self-verifies**: it compiles `esp32dev_v3` + `oled_v3` as its
 final step, so `docker build` failing means the firmware doesn't compile.
 
 ## Build the image
 
 ```sh
 # from the repo root
 docker build -t badge-fw .
 ```
 
 First build pulls the base image + pioarduino platform + xtensa toolchain (a few
 hundred MB, one time); they're cached in the image afterwards, so later container
 builds are fast and need no network.
 
 ## Build firmware
 
 Two modes:
 
 **A) Baked-in source** (self-contained — good for CI / a clean checkout):
 ```sh
 docker run --rm badge-fw pio run -e oled_v3        # the badge build (default env)
 docker run --rm badge-fw pio run -e esp32dev_v3    # serial dev build (deprecated)
 ```
 
 **B) Live working tree** (iterate on the host, build in the container):
 ```sh
 docker run --rm -v "$PWD/firmware:/project" badge-fw pio run -e oled_v3
 ```
 The mount shadows the baked-in source with your edits; the toolchain cache
 (`/opt/pio`) is separate, so builds still run offline. Build artifacts land in
 `firmware/.pio/build/<env>/` on the host (already git-ignored).
 
 > On Linux, a bind-mounted build writes `.pio` as root. Add `--user "$(id -u):$(id -g)"`
 > if you want host-owned artifacts.
 
 ## Get the binary out (baked-in mode)
 
 ```sh
 id=$(docker create badge-fw)
 docker cp "$id:/project/.pio/build/oled_v3/firmware.bin" ./firmware.bin
 docker rm "$id"
 ```
 (Mode B writes it straight to `firmware/.pio/build/...` on the host — no copy needed.)
 
 ## Flashing
 
 Flashing needs a USB serial port, which **Docker Desktop on macOS/Windows cannot
 pass into a container**. So:
 
 - **macOS / Windows:** build in the container, **flash from the host** with your
   local PlatformIO (`cd firmware && pio run -e oled_v3 -t upload`), or flash the
   extracted `firmware.bin` with esptool. (Host serial notes live in the
   `esptool-serial-access` memory.)
 - **Linux host:** you *can* flash from the container by passing the device:
   ```sh
   docker run --rm --device=/dev/ttyUSB0 -v "$PWD/firmware:/project" \
       badge-fw pio run -e oled_v3 -t upload --upload-port /dev/ttyUSB0
   ```
   (`/dev/ttyACM0` for native-USB boards.)
 
 ## Provisioning
 
 The Web-Bluetooth provisioning page (`provisioning/index.html`) is a **host +
 browser** task — BLE doesn't cross the container boundary, and it needs
 Chrome/Edge with Web Bluetooth. Serve it on the host:
 `cd provisioning && python3 -m http.server 8000`.
 
 ## Maintaining
 
 - **Bump PlatformIO Core:** change `ARG PLATFORMIO_VERSION` and rebuild. Keep it
   matched to the dev machine's `pio --version`.
 - **Bump the Arduino platform:** edit the pioarduino tag in
   `firmware/platformio.ini` (`[core3x]`) — the Dockerfile picks it up, no Docker
   edit needed.
 - **A new env that pulls new libs:** the warm layer installs deps for
   `esp32dev_v3` + `oled_v3`; if you add an env you want pre-warmed, add it to the
   `pio pkg install` line. Other envs still build, they just fetch their platform
   on first use.