platformio-builder

Simple Docker image for building with PlatformIO.

Image tags

• v<version>-dev — built from main, e.g. v6.1.19-dev
• v<version> — promoted release, e.g. v6.1.19
• latest — most recently promoted release

Usage

General

• Pass PUID and PGID at runtime (or use the wrapper) to match the host user. Defaults (1001:121) align with GitHub Actions.
• Clone some source code
• Mount source inside container as /work
• (Optional) Persist caches through named or host-mounted volumes:
  • PlatformIO at /home/pio/.platformio
  • Builder (npm) cache at /home/pio/.platformio-builder
• Run one-off pio builds/commands via ephemeral containers or bash to get an interactive shell and mess about

Direct usage

$ git clone https://github.com/MoonModules/WLED-MM.git
$ export PIO_BUILDER_CACHE_KEY="$(basename "$PWD")"
$ docker run --rm $([ -t 0 ] && echo '-t') $([[ "$-" =~ 'i' ]] && echo '-i') \
  --pull always \
  -e PUID="$(id -u)" \
  -e PGID="$(id -g)" \
  -v "$HOME/.platformio:/home/pio/.platformio" \
  -v "$HOME/.platformio-builder/$PIO_BUILDER_CACHE_KEY:/home/pio/.platformio-builder" \
  -v "$HOME/.platformio-builder/$PIO_BUILDER_CACHE_KEY/node_modules:/work/node_modules" \
  -v "${GITHUB_WORKSPACE:-$PWD}/WLED-MM:/work" \
  -w /work \
  ghcr.io/treyturner/platformio-builder:latest \
  pio --version

PlatformIO Core, version 6.1.19

Wrapper script

A wrapper with the above logic can be tweaked to your needs. Set PIO_BUILDER_TAG to pin a specific version:

PIO_BUILDER_TAG=v6.1.19 ./with_builder.sh pio run

Building

Build locally (queries PyPI for the latest PlatformIO version):

make build

Pin a specific PlatformIO version:

PLATFORMIO_VERSION=6.1.19 make build

Publishing

CI (automatic)

Pushing to main triggers the Build and publish dev workflow, which detects the latest PlatformIO version from PyPI and publishes a v<version>-dev image.

To build with a specific PlatformIO version, trigger the workflow manually and supply the platformio_version input.

Promoting to a release tag

Run the Promote dev version tag to release version tag workflow with:

Input	Description
platformio_version	Version to promote, e.g. 6.1.19
latest	If enabled, also retag the image as latest

This promotes v<version>-dev → v<version> (and optionally latest).