Miles Ward
e3452fe976
Full rename to match the openpxe.com brand. The product now reads as a
polished open-source project rather than a personal-tool nickname:
the anvil/forge metaphor is gone, replaced with the rainbow-horizon
brand mark from the marketing site.
## Naming changes
**PXEForge → OpenPXE** everywhere it's user-visible or developer-
facing:
- All 8 crate package names (`pxeforge-*` → `openpxe-*`).
- The bin crate dir + binary (`crates/pxeforge` → `crates/openpxe`,
`bin = "openpxe"`).
- Env vars: `PXEFORGE_*` → `OPENPXE_*` (no compat shim — pre-beta).
- Tracing targets: `pxeforge::*` → `openpxe::*`.
- Prometheus metrics: `pxeforge_*` → `openpxe_*` (pre-beta; nobody
has dashboards on these yet).
- Container image: `gitea.milesward.dev/mward4/openpxe:0.3.0`.
- All in-tree paths: `/var/lib/openpxe/{isos,work,smb}`,
`/usr/share/openpxe/ipxe`, `/etc/openpxe/...`.
- Unraid template renamed `pxeforge.xml` → `openpxe.xml`.
- README, NEXT_PHASE.md, architecture.md, comments, and the WebUI
brand string.
**Gated Deployment → Queued Deployment** as the user-facing concept:
- `Settings::TimeoutAction::GatedDeployment` →
`QueuedDeployment` (with `#[serde(alias = "gated_deployment")]`
so v0.2.0 settings.json files keep deserializing).
- Rust types: `Gate` → `QueueEntry`, `GateQueue` → `DeploymentQueue`,
`GateInner` → `QueueEntryInner`.
- File: `crates/core/src/gate.rs` → `crates/core/src/queue.rs`.
- HTTP routes: `/api/gate/*` → `/api/queue/*`. The JSON list key
flipped from `"gates"` to `"entries"` to match.
- iPXE shortcut: `/boot/_gate.ipxe` → `/boot/_queue.ipxe`. The
top-level menu's item id is now `queue` instead of `gate`.
- WebUI sidebar tab: "Forge Gate" → "Queue".
- Field on `AppState`: `gates` → `queue`.
## Brand assets
The anvil + forging-sparks logos are dropped:
- `logo.svg` is now a 24×24 medallion filled with the
`rainbow-horizon` gradient from openpxe.com (sliding hue rotation
via SMIL on the gradient stops, no JS needed).
- `anvil-forge.svg` renamed to `loader.svg` and rebuilt as a 64×64
louder version of the same disc — used for page-load transitions
and the imaging-progress widget. Adds a subtle scale pulse and a
white inner-glow so it has dimensionality on either theme.
## CSS rename
- `.forge-progress` → `.queue-progress`
- `.forge-progress .anvil` → `.queue-progress .mark`
- `@keyframes forge-sheen` → `queue-sheen`
- `.loader .anvil` → `.loader .mark`
- "Heating the forge…" loader text → "Loading…"
The rest of the layout is untouched. Light/dark theme tokens and the
sidebar/topbar structure carry over from v0.2.0 unchanged — the
brief was "keeping the UI similar."
## Validation
- `cargo build --workspace` — clean.
- `cargo clippy --workspace --all-targets` — no warnings.
- `cargo test --workspace` — **66 tests passing**, same as v0.2.0.
- Local smoke run against the rebuilt release binary verifies:
- `/boot.ipxe` emits `Queued Deployment` + `item queue` + chains
`/boot/_queue.ipxe`
- `/api/queue` returns `{count, entries}`
- `/metrics` emits `openpxe_queue_count` (renamed)
- `/assets/logo.svg` and `/assets/loader.svg` serve the new
rainbow brand SVGs
- `/api/status` reports version `0.3.0`
## Migration notes for operators on v0.2.0
- Container image path changed: pull
`gitea.milesward.dev/mward4/openpxe:0.3.0` (not `pxeforge:`).
- Bind mounts: `/var/lib/openpxe/{isos,work,smb}` (not `pxeforge`).
Move the host path or update the template.
- Env vars: replace `PXEFORGE_*` with `OPENPXE_*`. The Unraid
template at `deploy/unraid/openpxe.xml` is already updated.
- `settings.json` carries over transparently — the
`gated_deployment` value is accepted as an alias.
- HTTP API: any external scripts that hit `/api/gate/*` need to
switch to `/api/queue/*`. The JSON envelope key is `entries`
instead of `gates`.
157 lines
6.7 KiB
Markdown
157 lines
6.7 KiB
Markdown
# Phase 6 — recommendations
|
|
|
|
The v0.2.0 cut leaves OpenPXE in a state where the entire protocol stack
|
|
and operator UI are exercised by 66 automated tests, the container is
|
|
multi-arch buildable, and the image ships at ~97 MB. What's left before
|
|
this looks and feels like a 1.0 product is mostly **real-hardware
|
|
validation** plus a small batch of features that can only sensibly be
|
|
designed once we've watched real machines image.
|
|
|
|
This doc is a punch list, ordered by what I'd do first if I had a week.
|
|
|
|
## Tier 1 — must-do before we call anything "stable"
|
|
|
|
### 1. Real-hardware validation matrix
|
|
|
|
We have CI tests for every protocol leg, but no end-to-end PXE on real
|
|
firmware. Build a small matrix:
|
|
|
|
| client | firmware | OS family | pass criteria |
|
|
|-------------------------------------|-----------|------------|---------------------------|
|
|
| any 10-y-old mini-PC | Legacy BIOS | Ubuntu Server 24.04 | gets to GRUB / installer |
|
|
| Intel NUC / similar | UEFI x64 | Windows 11 | reaches "where do you want to install" |
|
|
| Raspberry Pi 4 | UEFI ARM64 | Raspberry Pi OS | gets to login prompt |
|
|
| Dell / HP business laptop | UEFI x64 | Fedora | one of: kernel boot or wimboot |
|
|
|
|
Add a `docs/HARDWARE_VALIDATION.md` checklist that records what worked,
|
|
firmware versions, and any quirks. Anything weird gets a regression
|
|
test in the relevant crate.
|
|
|
|
### 2. Boot menu hotkey + UI accessibility audit
|
|
|
|
The iPXE menu has number-key + letter hotkeys but no documentation on
|
|
what they map to. Generate a printable cheat-sheet from
|
|
`crates/http-api/src/ipxe_script.rs` so operators don't have to read
|
|
the source. Run a screen-reader pass over the web UI — most of it
|
|
should be fine since we're mostly tables + form labels, but the
|
|
Terminal pane and the SSE log output need explicit `aria-live`
|
|
regions.
|
|
|
|
### 3. Boot.wim re-patch detection
|
|
|
|
Bootimus v0.1.62's "fingerprint of patched inputs + Save & Re-patch"
|
|
pattern is a small but high-value feature: when an operator changes
|
|
the SMB host override or upgrades wimboot, the existing patched
|
|
boot.wim is silently stale. We should:
|
|
|
|
- Hash the inputs (smb_host, smb_share, startnet.cmd content,
|
|
wimboot binary digest) into the IsoMeta;
|
|
- Surface a "needs re-patch" warning on the Storage tab when the
|
|
hash drifts;
|
|
- Add a "Re-patch SMB" button that re-runs the WimPatcher.
|
|
|
|
## Tier 2 — features that round out pre-beta
|
|
|
|
### 4. Auto-install file library
|
|
|
|
iVentoy and Bootimus both support attaching `autounattend.xml` /
|
|
`preseed.cfg` / `kickstart.cfg` to an image. The mechanics are
|
|
straightforward: store files under `<work_dir>/autoinstall/<distro>/`,
|
|
expose CRUD via `/api/autoinstall-files`, and modify the WimPatcher
|
|
+ Linux kernel cmdline to fetch + apply the right file. Placeholders
|
|
worth supporting (Bootimus pattern): `{{MAC}}`, `{{HOSTNAME}}`,
|
|
`{{IP}}`, `{{SERVER_ADDR}}`, `{{IMAGE_FILENAME}}`, substituted
|
|
serve-side per request.
|
|
|
|
### 5. Wake-on-LAN trigger
|
|
|
|
A natural pair with per-MAC host bindings: bind a MAC to an image,
|
|
then click "Wake & Image" to send the magic packet and let OpenPXE
|
|
do the rest. Implementation is small (`udp/9` broadcast, magic packet
|
|
construction) but it makes the bound-host workflow feel instant.
|
|
|
|
### 6. Distro profile manifest
|
|
|
|
Today, distro detection lives as Rust match arms in `introspect.rs`
|
|
and the kernel cmdline templates live in `store.rs`. Bootimus extracts
|
|
this into a JSON manifest that ships embedded in the binary AND is
|
|
overridable by the operator at runtime — so a new distro can be added
|
|
without rebuilding the container. Worth porting; it'd let community
|
|
contributions land as PRs to a single JSON file.
|
|
|
|
### 7. Syslog receiver
|
|
|
|
`smee` ships one. The use case: WinPE / Linux installers can be
|
|
configured to syslog over the network to the PXE server; if we have
|
|
an endpoint and a place in the UI to view per-client diagnostics,
|
|
post-mortem on a failed install gets dramatically easier.
|
|
|
|
### 8. UEFI HTTP Boot validation
|
|
|
|
Option 60 = `HTTPClient` is wired up in `decide()` already, but
|
|
we've never tested it on real firmware. Some Dell + Lenovo UEFIs
|
|
prefer it over PXE-via-TFTP. A quick check on a real machine
|
|
(disable TFTP boot in firmware, force HTTP boot) and a regression
|
|
test would be nice.
|
|
|
|
## Tier 3 — bigger lifts, only if there's demand
|
|
|
|
### 9. Pure-Rust SMB server
|
|
|
|
`smbd` from Samba is ~80 MB of the runtime image. There are pure-Rust
|
|
SMB2 server crates (`smbd-server`, `smb-rs`) of varying maturity.
|
|
Replacing the dep would slim the image by ~40% and remove the
|
|
`CAP_SYS_ADMIN` requirement for SMB. Worth a spike, not necessarily
|
|
landable in Phase 6.
|
|
|
|
### 10. IPv6 / DHCPv6
|
|
|
|
PXE-over-IPv6 is real (RFC 5970). Some sites are v6-only. Worth
|
|
implementing once we know we have one. Until then, IPv4-only is the
|
|
right default — flipping the bit on v6 without v6 testing is asking
|
|
for silent breakage.
|
|
|
|
### 11. Multi-replica deployment
|
|
|
|
The current design assumes one OpenPXE per broadcast domain. Two
|
|
proxies on the same L2 will race; the deployment queue is in-memory, etc.
|
|
For HA we'd need to:
|
|
- Externalize the deployment queue (Redis, etcd) or lean into "the menu is
|
|
cheap to refetch if a replica dies";
|
|
- Ensure DHCP proxy replies are deterministic so a client always
|
|
gets the same answer regardless of which replica replied;
|
|
- Document the L2 collision domain story.
|
|
|
|
This is a large lift and should only happen if someone's actually
|
|
asking for it.
|
|
|
|
### 12. Pi 4 / SBC quirks
|
|
|
|
Raspberry Pi netboot uses a specific DHCP option-43 vendor field +
|
|
TFTP path layout that OpenPXE doesn't currently special-case. There's
|
|
a spec; the work is small once we have a Pi to test on.
|
|
|
|
## What I'd skip
|
|
|
|
- **A custom DHCP server (not proxy).** The proxy mode is the right
|
|
abstraction; full DHCP would need raw sockets + a lot of corner-case
|
|
handling for problems no operator wants us to solve.
|
|
- **A pluggable backend abstraction à la Tinkerbell.** Tinkerbell does
|
|
it because they integrate with k8s CRDs. OpenPXE's "the file system
|
|
IS the database" model is simpler and good enough for the target
|
|
audience. Don't add a Backend trait until something asks for it.
|
|
- **Multiple language UIs.** Bootimus added these in v0.1.62 and the
|
|
translations are LLM-generated. Skip until we have real users
|
|
asking for non-English.
|
|
|
|
## Quick wins (could land in a single afternoon)
|
|
|
|
- Add a Grafana dashboard JSON to `deploy/grafana/` driven off the
|
|
new `/metrics` endpoint.
|
|
- A `openpxe bench` subcommand that runs a 10-second internal load
|
|
test (synthetic queue joins) so an operator can sanity-check tuning.
|
|
- Ship a basic `docker-compose.yml` for the Unraid path that demos
|
|
the new themes / progress widget.
|
|
- Generate a printable single-page operator runbook from the README
|
|
+ architecture.md (e.g. `cargo xtask runbook`).
|