werkdock/docs/rfcs/0003-composable-toolchain-mounts.md

RFC 0003: Composable Toolchain Mounts

Status:

• proposed: 2026-09-01 (as a candidate — comes due when more than one toolchain combination is needed)
• accepted: -
• rejected: -

Proposal: Instead of baking every toolchain combination into its own flat image, werkdock composes a sandbox at run time: a slim base image plus per-toolchain artifacts from the store, mounted read-only under their own prefixes.

Context and Problem Statement

Werkdock images are flat trees without layers (see the Disk Footprint section of the README): every toolchain combination is a full archive, built, uploaded, and unpacked as a whole. The pain is concrete: adding Go and Node to the JDK build environment meant rebuilding and re-uploading a ~600 MB archive whose JDK half did not change. Docker solves this with content-addressed layers over overlayfs — which needs either root or an overlay-capable bwrap (0.9+), neither available on the target webspaces today.

The Key Insight

Overlayfs is only needed when trees must merge at the same paths. Toolchains that live under their own prefix need no merging at all — and the official tarball distributions do exactly that:

• Go unpacks to /usr/local/go
• Node unpacks to /usr/local/node-<version>
• Temurin JDKs unpack to /usr/local/jdk-<version>

So composition is plain bind mounts, available in every bwrap version, no root, no overlayfs:

werkdock run --rm --with jdk-21 --with go-1.24 --with node-20 base sh -c '...'

Sketch

• The base image shrinks to what apt must provide (debootstrap minbase, git, ca-certificates, locales — roughly 300 MB unpacked).
• A toolchain is a store artifact beside images: an unpacked tarball plus a small manifest naming its mount prefix and the environment it needs (PATH entries, JAVA_HOME, GOROOT, ...).
• --with NAME adds a read-only bind of the toolchain at its prefix and applies its manifest environment; order follows the flags, like -v.
• Deduplication falls out for free: each toolchain is stored once, every combination costs zero additional disk.

Limits

• Only tarball-distributed toolchains fit; apt-installed ones spread across /usr and cannot be prefix-mounted. For JDK, Go, and Node the official tarballs exist; toolchains without one stay in the base image.
• --with is a werkdock extension beyond the docker-compatible surface (RFC 0002) — docker has no counterpart. It is additive: level-1 compatibility of the remaining CLI is untouched.

Considered Alternatives

• On-target image building (apt/mmdebstrap on the webspace, unprivileged): technically possible via user namespaces, but slow, network-bound per build, and a relapse into the self-build drift step 21 corrects — build locally, install artifacts.
• Letting package managers fill a persistent home cache (Gradle toolchains, Go modules): works today as a side effect, but unhermetic and network-dependent on cold caches.
• Overlayfs layers or hardlink dedup between image versions: the general solutions, still worthwhile later, but blocked on bwrap 0.9+ (overlay) or more store machinery (dedup) — composition needs neither.

Decision Outcome

Pending — to be decided when a second toolchain combination is actually needed (for example Werkbaum pinning its own Node version). Until then the one fat image (RFC 0002 outcome, plan step 21) stays the deliberate choice.