mward4/OpenPXE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 40 Wiki Activity

v0.3.0 — rebrand: PXEForge → OpenPXE, Gated → Queued Deployment

Browse Source 
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`.
This commit is contained in:
Miles Ward
2026-05-06 14:13:38 -04:00
parent c607f2e31c
commit e3452fe976
56 changed files with 755 additions and 802 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+29 -29
View File
@@ -1,4 +1,4 @@
# PXEForge architecture
# OpenPXE architecture
## Protocol stack
@@ -8,7 +8,7 @@ Client firmware PXE ROM
│ DHCPDISCOVER (UDP/67 broadcast, option 60 "PXEClient", option 93 arch)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ PXEForge │
│ OpenPXE │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ DHCP proxy │ │ TFTP server │ │ HTTP server (axum) │ │
@@ -33,7 +33,7 @@ Client runs iPXE
│
│ DHCPDISCOVER with option 77 "iPXE"
▼
PXEForge sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe
OpenPXE sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe
│
│ HTTP GET /boot.ipxe (iPXE menu, auto-generated from IsoStore)
▼
@@ -48,14 +48,14 @@ Kernel boots with distro-specific args pointing back at /iso/<id>.iso
| Crate | Responsibility |
|---------------------|-------------------------------------------------------------------|
| `pxeforge-core` | Shared types: `Config`, `ClientArch`, `FirmwareClass`, `ClientRegistry` |
| `pxeforge-ipxe-assets` | Embeds bundled iPXE binaries via `rust-embed` |
| `pxeforge-iso-store` | On-disk ISO store, introspection, boot-entry generation |
| `pxeforge-dhcp-proxy` | UDP listener + `dhcproto` reply builder; pure `decide()` unit-testable |
| `pxeforge-tftp` | RFC 1350 + OACK (blksize / tsize / windowsize). Serves only embedded assets — no filesystem |
| `pxeforge-http-api` | `axum` router: web UI, API, iPXE script generation, ISO streaming |
| `pxeforge-webui` | Single `index.html` served as static string |
| `pxeforge` (bin) | Wires everything together, runs the three servers concurrently |
| `openpxe-core` | Shared types: `Config`, `ClientArch`, `FirmwareClass`, `ClientRegistry` |
| `openpxe-ipxe-assets` | Embeds bundled iPXE binaries via `rust-embed` |
| `openpxe-iso-store` | On-disk ISO store, introspection, boot-entry generation |
| `openpxe-dhcp-proxy` | UDP listener + `dhcproto` reply builder; pure `decide()` unit-testable |
| `openpxe-tftp` | RFC 1350 + OACK (blksize / tsize / windowsize). Serves only embedded assets — no filesystem |
| `openpxe-http-api` | `axum` router: web UI, API, iPXE script generation, ISO streaming |
| `openpxe-webui` | Single `index.html` served as static string |
| `openpxe` (bin) | Wires everything together, runs the three servers concurrently |
## Key decisions and why
@@ -75,11 +75,11 @@ so plain `SOCK_DGRAM` is enough.
1. Firmware PXE ROM sends DHCPDISCOVER with option 60 = `PXEClient`,
option 93 = arch.
2. PXEForge replies with TFTP server + arch-specific iPXE binary
2. OpenPXE replies with TFTP server + arch-specific iPXE binary
(`undionly.kpxe` for Legacy BIOS, `snponly.efi` for x86_64 UEFI, etc.).
3. Client TFTPs the iPXE binary and runs it.
4. iPXE does its own DHCP, setting option 77 (user-class) to `iPXE`.
5. PXEForge detects the user-class and this time replies with an HTTP URL
5. OpenPXE detects the user-class and this time replies with an HTTP URL
in option 67 pointing at `/boot.ipxe`.
6. iPXE fetches and executes that script, which chains the selected OS.
@@ -105,7 +105,7 @@ Whatever we do for Windows, we never:
- instruct users to enable `bcdedit /set testsigning on`
- install any certificate into the target's root/trust store
iVentoy's `httpdisk.sys` approach broke this rule. PXEForge doesn't.
iVentoy's `httpdisk.sys` approach broke this rule. OpenPXE doesn't.
### Linux ISO boot uses kernel+initrd extraction, not sanboot
@@ -157,13 +157,13 @@ release:
root-owned" problem that breaks ISO upload on standard Docker hosts.
- `/healthz` and `/readyz` split from `/api/status` — readyz fails if no
iPXE binaries are bundled, giving K8s probes a real signal.
- Startup aborts with a clear error if `PXEFORGE_PUBLIC_IP` can't be
- Startup aborts with a clear error if `OPENPXE_PUBLIC_IP` can't be
auto-detected (no more silent `127.0.0.1` advertisement).
- `scripts/fetch-ipxe.sh` fails non-zero if zero binaries download; the
Dockerfile uses arch-scoped paths (`x86_64-efi/snponly.efi` etc.).
**Windows boot plumbing** (new):
- `pxeforge-iso-store::smb::SmbManager` supervises `smbd` on the Windows
- `openpxe-iso-store::smb::SmbManager` supervises `smbd` on the Windows
toggle: `start` → spawn + write `smb.conf`; `reconcile` → SIGHUP on
share changes; `stop` → SIGTERM. `SmbState` surfaced to the UI for
visibility.
@@ -177,32 +177,32 @@ release:
- ISO sizes in menu labels (`[ 4376 MB]`), iVentoy format.
- `Reboot Computer` + `Exit and continue BIOS boot` in Tools menu.
- Number-key hotkeys (1..9) on boot entries, letter hotkeys on tools.
- Clients tab cross-joins the gate queue so an operator sees "at gate #2"
- Clients tab cross-joins the deployment queue so an operator sees "in queue #2"
or "assigned: ubuntu-linux" status inline.
**Developer ergonomics** (new):
- `pxeforge seed --from <path>` CLI to import ISOs from a directory.
- `openpxe seed --from <path>` CLI to import ISOs from a directory.
Same pipeline as web upload (slug, sha256, introspection, boot-entry).
- `docker-compose.yml` with `pxeforge` (host network, real PXE) and
`pxeforge-dev` (published ports, DHCP disabled, for API testing).
- `docker-compose.yml` with `openpxe` (host network, real PXE) and
`openpxe-dev` (published ports, DHCP disabled, for API testing).
**API cleanliness**:
- All timestamps now serialized as RFC 3339 strings (the `time` crate's
default 9-tuple broke browser `Date` parsing).
- Gate poll retains assignment until the operator releases it; if the
- Queue poll retains assignment until the operator releases it; if the
client's chain fails, it reuses the assignment instead of falling back
to the menu.
## Phase 4 — UI restructure + remote storage
The web UI was rebuilt around six tabs (Dashboard / Network / Forge Gate /
The web UI was rebuilt around six tabs (Dashboard / Network / Queue /
Storage / Terminal / About) inspired by the iVentoy layout the user
attached and Netbox Labs's compact-card pattern. The old hierarchical
"Monitoring / Content / Configuration" sidebar grouping is gone — every
tab is one click from the brand bar.
**NFS share manager** (`crates/iso-store/src/nfs.rs`):
- Operators add a remote share via Storage → NFS shares; PXEForge mounts
- Operators add a remote share via Storage → NFS shares; OpenPXE mounts
it under `<work_dir>/nfs/<id>/` and walks it for `*.iso` files.
- Each ISO found is registered with `IsoStore::register_external` using
a new `IsoSource::Nfs { mount_id, relative_path }` variant. The store
@@ -227,7 +227,7 @@ tab is one click from the brand bar.
followed by live updates. Slow clients see a `lagged` event rather
than dropping the stream.
- `/api/terminal` accepts a single command line and dispatches to a
whitelist (`status`, `isos`, `clients`, `gate {list,assign,release}`,
whitelist (`status`, `isos`, `clients`, `queue {list,assign,release}`,
`nfs {list,mount,unmount,scan}`, `smb {status,start,stop,reload}`,
`log {clear,tail}`). Output is mirrored onto the LogBus so reading the
live tail tells the same story as scrolling the terminal pane.
@@ -240,7 +240,7 @@ tab is one click from the brand bar.
read-only by design — silently changing the public IP on a hot UI
would break PXE for every client mid-boot.
- The only writable network field is `dns_server`, an optional
informational hint stored in `Settings`. PXEForge does not run a DNS
informational hint stored in `Settings`. OpenPXE does not run a DNS
server; the field exists so operators don't have to dig out the
upstream DNS at 3 AM.
@@ -252,7 +252,7 @@ tab is one click from the brand bar.
warning.
- Dashboard surfaces a "Images that won't boot" panel reusing the same
predicate, so the operator sees the problem before they pick the ISO
in the gate.
in the queue.
- Streaming uploads are already in place via axum multipart; the v0.1.62
fix to "502 on big upload" doesn't apply.
@@ -260,7 +260,7 @@ tab is one click from the brand bar.
**Per-MAC host bindings** (`crates/core/src/host_bindings.rs`):
- New `HostBindings` registry maps a MAC → preferred `BootEntry::id`
(or one of the reserved menu shortcuts `_local`, `_gate`,
(or one of the reserved menu shortcuts (`_local`, `_queue``,
`_tools_menu`).
- Persisted to `<work_dir>/hosts.json`. Like `SettingsStore`, in-memory
is authoritative — disk corruption falls back to empty rather than
@@ -278,7 +278,7 @@ tab is one click from the brand bar.
- Counters: DHCP replies (per arch label), DHCP declined, TFTP
transfers (per status label), TFTP bytes, HTTP requests (per route
label).
- Gauges: ISO count, client count, gate count, gate-imaging count,
- Gauges: ISO count, client count, queue count, queue-imaging count,
NFS active mounts, uptime, build info.
- Exposed as plain Prometheus text at `/metrics`.
@@ -295,7 +295,7 @@ other idiom fixes.
- New SVG logos: a refined anvil (`logo.svg`) and a SMIL-animated
`anvil-forge.svg` (rising sparks + pulsing underglow). Pure SVG —
no GIFs, no CSS keyframes for the sparks.
- "Forge progress" widget on the Dashboard and Forge Gate: animated
- "Forge progress" widget on the Dashboard and Queue: animated
anvil paired with a `linear-gradient(warn → accent)` progress bar
with a moving sheen. Goes idle (greyscale, no sheen) at zero
imaging load.