Master installer image: one stick provisions a Pithead coordinator, a RigForge rig, or both

[VijitSingh97]

Direction set by the operator (2026-07-31): the appliance image becomes the ONE way to stand up
any machine in a mine. The installer page's first question becomes what this machine IS:

• Pithead — the current flow, unchanged: coordinator + nodes + dashboard.
• RigForge rig — the form collapses to almost nothing: pool address (default discovered via
  mDNS — a Pithead on the LAN answers pithead.local:3333), optional worker name and stratum
  password. First boot from disk compiles XMRig once (cached on /data), tunes what a read-only
  root allows, and mines. No dashboard, no nodes, no chains partition needed — the repart
  layout can size /data small.
• Both — Pithead plus the on-box miner (The appliance offers mine-on-this-box but gives no way to install RigForge on it #796 option 3): RigForge runs beside the
  containers, pointed at the machine's own stratum.

The fleet story this buys: flash one stick, install machine 1 as Pithead, then walk the same
stick down the rack installing rigs — each one finds the coordinator over mDNS and asks only
for confirmation. The stick already keeps clean session state per machine and carries operator
pre-seeds; both mechanisms extend to rig configs unchanged.

Groundwork this depends on (from the #796 recon, unverified on the RO root until the bench
prototype): RigForge units rendered into /run rather than /etc; GRUB/1GB-hugepage tuning
declared image-owned (runtime sysctl tuning only, or moved to image build); the RigForge tree
synced to /data so the XMRig build lands on writable storage; toolchain baked at image build
(apt cannot run on the appliance).

Open questions for the recon session:

• image identity and naming once it installs two products (org umbrella?), and how the image
  version couples to each product's version;
• whether the rig role skips the containers entirely (no podman surface on a pure rig) or
  keeps the base identical for simpler A/B updates — leaning identical-base: one image, one
  update pipeline, roles differ only in what the boot path starts;
• credentials card per role (a rig has no dashboard login — its card is just the worker name
  and where it points).

Sequence: bench prototype of RigForge-on-appliance over SSH on the debug image (recon, after
the operator's Monero sync completes) → rigforge-side RO-root changes → #796 (Both) → this.

[VijitSingh97]

The plan, phased so every step ships something testable

The interface rule that governs all of it: the existing one-page flow IS the product —
progressive disclosure from a single question, validation before anything irreversible, one
credentials card, machine does the rest. Adding the role question must not add a second page:
it becomes the FIRST disclosure, above the disk, and everything downstream reshapes to it —
exactly how the disk choice already reshapes the form today.

Phase R0 — recon on the bench (next session, after the operator's Monero sync)

Prototype RigForge on the debug appliance over SSH: baked-toolchain image variant, tree synced
to /data, run setup with a pre-written config against the box's own stratum. Deliverable: the
verified list of RigForge changes the RO root actually needs (expected: /run units, GRUB-tune
skip, build-dir override — but the bench decides, not the prediction).

Phase R1 — RigForge appliance mode (rigforge repo)

The changes R0 proved: an env/flag under which rigforge skips apt (deps pre-baked), renders its
unit into /run, tunes only what runtime allows, and builds under a caller-named dir. Gated by
rigforge's own CI plus one pithead stack test driving the flag.

Phase R2 — "Both" on the current image (#796)

Image bakes toolchain + rigforge tree; pithead-sync grows a rigforge leg; pithead render
writes rigforge's config.json (127.0.0.1:3333 + stratum password from .env) and starts the
/run unit when local_miner.enabled. The wizard's existing "Mine on this machine too?" answer
becomes TRUE — same select, no new UI. First enable compiles once, narrated on the console.
KVM: provision phase gains a local-miner leg (enable → xmrig process up → shares reach p2pool).

Phase R3 — the role question (this issue)

The installer page opens with one select above the disk: What is this machine?

• Pithead → today's flow, byte for byte.
• RigForge rig → the form collapses to: pool address (pre-filled by mDNS discovery of a
  Pithead on the LAN), worker name, optional stratum password. The card shows the worker name
  and where it points — no dashboard credentials, because a rig has none.
• Both → Pithead's form; the miner rides the existing local_miner switch.
  The disk section, wipe semantics, validation-before-erase, self-power-off and headless first
  boot are IDENTICAL in every role — one flow, three shapes.

Phase R4 — role plumbing under the same A/B contract

One image, one update pipeline, identical base; the role is a /data marker the boot path reads:
rig boots start rigforge's unit instead of the compose stack. repart sizes /data small for
rigs (no chains). verify-image asserts both role paths; the update phase proves a rig A/B
updates exactly like a coordinator.

Phase R5 — fleet polish

The stick's per-machine clean-session behavior (already shipped) + pre-seeds extend to rig
configs; walk-the-rack provisioning becomes: same stick, pick role, pick disk, confirm.
Naming/branding decision (org umbrella) lands here, before any public cut.

Each phase gates on the standing bars: KVM battery green, docs in voice, coverage at tier.

[VijitSingh97]

Role taxonomy confirmed by the operator — the select reads exactly:

• Pithead — coordinator + nodes + dashboard (today's flow, untouched)
• Pithead + RigForge — the coordinator that also mines with its own CPU
• RigForge — a rig: pool address, worker name, disk, nothing else

The bench machine (HP, currently a Pithead with remote Tari via gouda.lan and a syncing local
Monero node) is the designated first Pithead + RigForge: R0's recon prototypes RigForge on
it over SSH, and R2 lands as its upgrade — so the plan's first two phases produce the
operator's own target machine rather than a test artifact.

[VijitSingh97]

Rig role addendum (operator direction): RigForge runs FROM the USB stick

The existing "USB-resident is unsupported" warning is chain-reasoning — 250 GB of writes and
disk-speed needs that a rig simply does not have. A RigForge machine holds almost no state
(pool address, worker name, one compiled binary), so for the RigForge role the stick IS the
install medium and the runtime:

• The disk question becomes optional for this role only: "Run from this USB stick" is a
  first-class choice beside the disks — boot, pick role, paste the pool address, mining. No
  erase, no power-off cycle, no commitment on machines whose disks belong to something else.
  Installing to a disk stays offered for permanent rigs.
• Write minimization makes stick wear a non-issue: volatile journald for the rig role, no swap,
  and a PREBUILT generic-arch XMRig in the image so the first boot need not compile at all —
  the native-tuned recompile becomes an option (cached once on the stick's small /data), not a
  requirement.
• repart already sizes /data to the medium; a 16 GB stick is plenty with no chains.
• A/B updates still work against the stick's own slots; "reflash the stick" is also an
  acceptable update story at rig scale.
• The unplugged-stick failure mode is a dead miner, not lost data — acceptable by construction.

This folds into R3/R4: the role select's RigForge branch gains the run-from-USB choice, and the
boot path's rig leg must tolerate (and prefer) a removable root.

[VijitSingh97]

R0 recon complete — RigForge runs on the appliance, and the bench decided the change list

Ran on the HP bench box (debug image, RC19-era build fca51b5, Monero fully synced) over SSH.
The prototype went end to end: toolchain installed under a temporary rw remount to stand in for
a baked-toolchain image, tree at /data/rigforge, ./rigforge.sh setup against the box's own
stratum. The rig mines: MSR preset applied, dataset at 100% huge pages (2 MB), ~1.5 kH/s on
3 threads, and the proxy accepted shares at 127.0.0.1:3333. A reboot test plus a re-run
proved every volatility claim below rather than inferring it.

The verified list (each item observed on the bench, not predicted)

1. Toolchain must be baked at image build — a later install cannot work. / and /usr
   are RO, so apt fails outright on the shipped image. Deeper: even installing under a rw
   remount leaves apt's /etc state (alternatives symlinks, ld.so.cache, dpkg config) on the
   volatile /etc overlay — after the reboot, gcc/cmake/git survived in /usr but
   cc/c++ resolution was broken. Bake at build time, where the /etc lower layer receives
   the alternatives.
2. The GRUB leg aborts setup and must be skipped. grub-mkconfig failed on the RO /boot
   (cannot create /boot/grub/grub.cfg.new) and the un-guarded sudo update-grub took the
   whole run down (exit 2) — after a completed 100% compile. The clean skip already exists:
   with GRUB_DEFAULT pointing at a nonexistent path, setup takes its designed
   "Skipping GRUB updates" branch and finishes (exit 0). R1's appliance flag should take that
   branch deliberately. Consequence: the 1 GB-hugepage cmdline becomes image-owned; without it
   XMRig logs failed to allocate RandomX dataset using 1GB pages and falls back to 2 MB pages
   at 100% — working, with a small known cost.
3. Every persistent-config write lands on the volatile /etc overlay and vanishes at
   reboot. The complete rigforge footprint, measured from the overlay upper: xmrig.service
   • its multi-user.target.wants symlink, modules-load.d/msr.conf, two fstab hugetlbfs
     lines, two limits.conf memlock lines, logrotate.d/xmrig. All gone after reboot; the
     service did not come back. R1: render the unit into /run/systemd/system with
     enable --runtime, modprobe msr and mount hugetlbfs at runtime instead of appending to
     files that do not persist.
4. The re-render-every-boot model already works. After the reboot, a plain re-run from the
   persistent /data/rigforge tree (build cached, compile skipped) restored the unit, tuning,
   and mining — exit 0 — even with the compiler half-broken. This is exactly the R2 shape:
   pithead-boot runs a rigforge leg each boot. Notably the re-run needed no working compiler,
   so a prebuilt binary + optional recompile (the USB-rig addendum) is consistent with what the
   bench showed.
5. The hugepage budget needs a single owner in the Both role. rigforge's
   sysctl vm.nr_hugepages=1221 overwrote pithead's 3072; the kernel shrank the pool to the
   in-use floor (2614 first run, 1444 after the reboot re-run) with zero free pages — no
   headroom for a container restart on either side. Whoever writes last wins. R2: pithead
   render computes the merged budget when local_miner.enabled, and rigforge's appliance mode
   stops writing vm.nr_hugepages.
6. No build-dir override needed. HOME_DIR: DYNAMIC_HOME roots the workspace under the
   script dir, so a tree at /data/rigforge puts the XMRig build on writable storage by
   placement alone (/data/rigforge/data/worker). The predicted change evaporates.
7. Dependency naming is Ubuntu-flavored and breaks Debian DIY today — linux-tools-common
   does not exist in trixie, and apt's all-or-nothing transaction fails the entire dependency
   install. Debian's package is linux-cpupower. Filed separately on rigforge (this is a DIY
   bug independent of the appliance).
8. XMRig source arrives by git clone at build time — the image needs the source vendored
   (or a prebuilt binary) for the no-clearnet install story.

What needed no change at all: runtime MSR (register values for "intel" preset have been set successfully), the performance governor via ExecStartPre (sysfs write, fine on the RO root),
runtime 2 MB hugepage reservation, XMRig auto-tuning, stratum against the box's own proxy.
The existing env-override surface (SYSTEMD_DIR, GRUB_DEFAULT, FSTAB, LIMITS_CONF,
MODULES_LOAD_DIR, LOGROTATE_DIR) covers every path R1 has to move — the appliance flag is
mostly presets plus skip-apt plus skip-sysctl.

Bench state

Left mining (~1.5 kH/s, the operator's designated Pithead+RigForge box). The unit is volatile
by nature until R2's boot leg exists: the next reboot stops the miner and restores pithead's
hugepage tuning; re-running GRUB_DEFAULT=/nonexistent ./rigforge.sh setup in
/data/rigforge brings it back. Setup logs on the box at /data/rigforge/setup-r0-run{1,2,3}.log.
The toolchain this prototype installed rides slot A only and disappears with the next A/B
update — as it should, since the real one gets baked.

[VijitSingh97]

Follow-up on finding 5 (hugepage budget) with live measurements from the bench, answering max-vs-sum:

Measured concurrent holdings (smaps, while both sides mine/verify): p2pool ~1299 × 2MB pages (its RandomX dataset, ~2.6 GB), monerod ~129 (RandomX verify cache), xmrig ~2.3 GB of dataset (in 3×1GB pages when the pool is unfragmented, else ~1168 × 2MB) + ~16 small pages. Both sides hold pages at the same time.

Which is larger: pithead's boot reservation (3072 pages / 6 GB) is larger than rigforge's computed miner need (1221 / 2.4 GB). But max() is a bet, not a budget: it only fits because pithead's 3072 carries ~2× headroom over its current 1428-page usage — the moment pithead's side grows into its own reservation, the miner starves (or vice versa). Sum of declared budgets is the honest sizing (~8.4 GB on the 16 GB bench — fits; the dashboard's mode-aware RAM floor must add the miner's share in the Both role).

Division of labor now in place:

• rigforge side (shipped as rigforge#328 / PR rigforge#329, bench-verified): the runtime write is grow-only and availability-based — it never shrinks an existing pool, grows by the shortfall only, and is a no-op when free+held already covers the miner. This makes write ordering between the two products safe regardless of who runs first.
• pithead side (R2, this issue): when local_miner.enabled, render owns the merged budget — its own reservation plus the miner's requirement (rigforge#305's hugepages_reserve_extra_mb is the designed hand-off: pithead writes rigforge's config.json with the stack's headroom declared, and rigforge sizes the whole pool as the single writer). pithead's own blind vm.nr_hugepages=3072 write should become grow-only the same way when R2 lands.

🤖 Generated with Claude Code

[VijitSingh97]

R2 implemented — PR #812 (Both on the current image, closes #796)

Follows the phased plan + the R0 findings + the hugepage follow-up:

• Baked at image build: rigforge toolchain (trixie's linux-cpupower, per rigforge#327), pinned rigforge tree at ARG RIGFORGE_REF (currently the rigforge#330 merge commit on develop — no tagged release carries appliance mode yet; the pin moves to the next rigforge tag), and a prebuilt XMRig at rigforge's own pin so the Tor-only box never needs the github clone (R0 finding 8).
• Synced every boot: rigforge program tree → /data/rigforge (DYNAMIC_HOME puts the build on writable storage, R0 finding 6); the prebuilt seeds the workspace only when the pinned commit changed — a native rebuild of the same pin is kept.
• Boot order: pithead-boot runs pithead local-miner last, after the health-gated mark-good — the miner needs the stratum listening and must never delay or block the slot commit. setup and apply run the same leg, so first provisioning and dashboard toggles converge without a reboot.
• Hugepage ownership (finding 5 + follow-up): render declares the stack's budget as hugepages_reserve_extra_mb: 6144 in rigforge's config (rigforge#305 hand-off) — rigforge's grow-only sysctl sizes the whole pool as the single writer; pithead's own vm.nr_hugepages write is now grow-only too.
• KVM: the provision phase submits local_miner=true and asserts enable → xmrig unit+process up → a share logged accepted by the proxy → miner back after the unaided reboot. Battery not run from this environment — it and the amd64 image build head to the bench next (list in the PR).

Deliberately deferred: the dashboard's mode-aware RAM floor adding the miner's share in the Both role (needs an env plumb into the dashboard container — small separate change).

🤖 Generated with Claude Code