Name update

2026-04-30 00:02:29 -04:00
parent 3517c67831
commit a9c4f408a9
3 changed files with 325 additions and 0 deletions
@@ -0,0 +1,136 @@
+# PXEForge on Unraid
+
+Three paths from "I have an Unraid box with Gitea on it" to "PXE clients
+boot from PXEForge". Pick the one that matches what you have.
+
+## Path A — build on Unraid, push to Gitea registry, pull by tag
+
+Recommended once you've done it once. Image is published to
+`gitea.milesward.dev/mward4/pxeforge:0.1.0` (or your equivalent) and
+every Unraid template / docker-compose just references the tag.
+
+Pre-flight:
+
+- Gitea has the **Container Registry** enabled (Site Admin → Configuration → set
+  `[packages] ENABLED = true` in `app.ini`; default-on in Gitea ≥ 1.18).
+- You have a Gitea **personal access token** with `write:package` scope
+  (User → Settings → Applications → Generate New Token, check `package`
+  read+write).
+
+Run on the Unraid host (Settings → Terminal, or `ssh root@unraid`):
+
+```bash
+# Pull just the build script straight from Gitea (no clone needed first):
+GITEA_TOKEN=<your-token>
+curl -fsSL \
+  -H "Authorization: token $GITEA_TOKEN" \
+  http://localhost:3000/mward4/PXEForge/raw/branch/main/scripts/build-and-publish-unraid.sh \
+  -o /tmp/pxeforge-publish.sh
+
+# Run it. ~6 min on Unraid hardware (native amd64, no QEMU).
+chmod +x /tmp/pxeforge-publish.sh
+GITEA_TOKEN=$GITEA_TOKEN /tmp/pxeforge-publish.sh
+```
+
+What it does:
+
+1. Shallow-clones the repo from local Gitea (no Cloudflare, no LAN issues).
+2. Runs `scripts/fetch-ipxe.sh` to grab the iPXE binaries from the official
+   release URLs.
+3. `docker build` against `deploy/docker/Dockerfile`.
+4. `docker login gitea.milesward.dev:3000` using a temp `DOCKER_CONFIG`
+   so the credential never lands in your real `~/.docker/config.json`.
+5. `docker push` both `:0.1.0` and `:latest`.
+6. Logout, scrub the temp config, delete the workspace.
+
+After it finishes, in Unraid → Docker → Add Container, set:
+
+| Field      | Value                                           |
+|------------|-------------------------------------------------|
+| Repository | `gitea.milesward.dev/mward4/pxeforge:0.1.0`     |
+| Network    | `host`                                          |
+| Extra args | `--cap-add=NET_BIND_SERVICE`                    |
+
+Volume mounts (paths inside container in **bold**):
+
+- **`/var/lib/pxeforge/isos`** ↔ `/mnt/user/appdata/pxeforge/isos`
+- **`/var/lib/pxeforge/work`** ↔ `/mnt/user/appdata/pxeforge/work`
+- **`/var/lib/pxeforge/smb`**  ↔ `/mnt/user/appdata/pxeforge/smb`
+
+Or skip the manual UI by dropping `pxeforge.xml` (in this directory)
+into `/boot/config/plugins/dockerMan/templates-user/` and Unraid will
+list it as a one-click template.
+
+Web UI: `http://<unraid-ip>/`.
+
+## Path B — `docker-compose up` directly from cloned repo
+
+Skip the registry entirely. Useful for "hack on it locally" iterations.
+
+```bash
+ssh root@unraid
+cd /mnt/user/appdata
+git clone http://localhost:3000/mward4/PXEForge.git pxeforge-src
+cd pxeforge-src
+bash scripts/fetch-ipxe.sh
+docker compose -f docker-compose.yml up -d --build pxeforge
+```
+
+The bundled `docker-compose.yml` already wires host networking, the
+right cap_add, and bind-mounts to `./data/`. Edit those bind-mount
+paths if you want them under `/mnt/user/appdata/pxeforge/`.
+
+## Path C — `docker load` from a tarball I built off-box
+
+For when the build host can reach Unraid but Unraid can't reach the
+internet. Build the image somewhere with a cargo + buildx environment,
+then:
+
+```bash
+# On the build host
+docker save pxeforge:0.1.0 | gzip > pxeforge-0.1.0.tar.gz
+
+# Transfer (rsync / scp / SMB / ZFS-replicate / sneakernet)
+scp pxeforge-0.1.0.tar.gz root@unraid:/tmp/
+
+# On Unraid
+gunzip -c /tmp/pxeforge-0.1.0.tar.gz | docker load
+docker tag pxeforge:0.1.0 gitea.milesward.dev/mward4/pxeforge:0.1.0
+```
+
+If you want it pullable by tag from other Unraid templates, push to
+Gitea afterward (path A's last step).
+
+## Verifying it works
+
+Once the container is up, from any LAN host:
+
+```bash
+# Should return 'ok'
+curl -s http://<unraid-ip>/healthz
+# Should return 'ready' if iPXE binaries are bundled
+curl -s http://<unraid-ip>/readyz
+```
+
+Web UI: `http://<unraid-ip>/`. The Dashboard's top-bar pill should
+read `● ready`. Upload an ISO, boot a test machine PXE → it should
+show up in the Dashboard's "Recent connections" table within seconds.
+
+## Common gotchas
+
+- **DHCP collision.** Don't run two PXE _proxies_ on the same broadcast
+  domain. PXEForge runs in proxy mode and never offers IP leases, so
+  it coexists with whatever DHCP server is already on the network —
+  but two proxies racing each other will whichever-wins at random.
+- **Host networking only.** Bridge mode containers don't see broadcast
+  DHCP. There's no working bridge-mode config for a PXE server.
+- **Permissions on `/mnt/user/appdata/pxeforge`.** The container runs
+  as uid 10001 by default. The entrypoint chowns the bind mounts to
+  10001 on first start, but only if the container itself has root —
+  `--user=root` isn't needed; the multi-stage Dockerfile starts as
+  root, fixes perms, then drops to pxeforge via gosu.
+- **NFS mounts in the Storage tab.** Mounting NFS inside the container
+  needs `CAP_SYS_ADMIN`. To enable, add `--cap-add=SYS_ADMIN` to the
+  Unraid template's "Extra args" — but understand that's a meaningful
+  capability, comparable to `--privileged`. Skip it if you only need
+  uploads.
@@ -0,0 +1,75 @@
+<?xml version="1.0"?>
+<!--
+  Unraid Docker template for PXEForge.
+
+  Drop this file into /boot/config/plugins/dockerMan/templates-user/
+  on your Unraid box (or import via the Docker tab → "Add Container" →
+  "Template Repositories" if you publish it on a Gitea raw URL).
+
+  IMPORTANT: PXEForge needs host networking for DHCP/TFTP raw broadcasts.
+  Bridge mode will NOT work — clients can't see broadcast DHCP from a
+  bridged container. The template forces NetworkType=host below.
+
+  Required ports (already host-bound by the binary; no Unraid mapping
+  needed in host mode):
+    udp/67    DHCP proxy
+    udp/69    TFTP
+    udp/4011  PXE Boot Server
+    tcp/80    HTTP (web UI + iPXE scripts + ISO range streaming)
+    tcp/445   SMB (only when Windows boot is toggled on)
+
+  Web UI: http://<unraid-ip>/  (port 80)
+-->
+<Container version="2">
+  <Name>PXEForge</Name>
+  <Repository>gitea.milesward.dev/mward4/pxeforge:latest</Repository>
+  <Registry>https://gitea.milesward.dev/mward4/-/packages/container/pxeforge</Registry>
+  <Network>host</Network>
+  <MyIP/>
+  <Shell>sh</Shell>
+  <Privileged>false</Privileged>
+  <Support>https://gitea.milesward.dev/mward4/PXEForge/issues</Support>
+  <Project>https://gitea.milesward.dev/mward4/PXEForge</Project>
+  <Overview>
+    Air-gapped network PXE boot server. Container-native Rust
+    implementation — DHCP proxy + TFTP + iPXE chainload + HTTP ISO
+    streaming, all in one process. Web UI for ISO upload, NFS share
+    mounting, and Gated Deployment ("horse-race" simultaneous launch
+    of one ISO across many waiting clients).
+
+    NEVER touches the client OS trust store: no test-signed drivers,
+    no testsigning toggle, no httpdisk.sys. Windows boot uses vanilla
+    Microsoft-signed WinPE + SMB share.
+  </Overview>
+  <Category>Network:Other Network:Management</Category>
+  <WebUI>http://[IP]/</WebUI>
+  <TemplateURL/>
+  <Icon>https://gitea.milesward.dev/mward4/PXEForge/raw/branch/main/crates/webui/src/logo.svg</Icon>
+  <ExtraParams>--cap-add=NET_BIND_SERVICE</ExtraParams>
+  <PostArgs/>
+  <CPUset/>
+  <DateInstalled/>
+  <DonateText/>
+  <DonateLink/>
+  <Requires>
+    Host networking. Unraid&#39;s built-in DHCP server (if any) must
+    not collide with a network that already has DHCP — PXEForge runs
+    in proxy mode and coexists, but only one DHCP _proxy_ should reply
+    per broadcast domain.
+  </Requires>
+  <Config Name="ISOs" Target="/var/lib/pxeforge/isos" Default="/mnt/user/appdata/pxeforge/isos"
+          Mode="rw" Description="Where uploaded and seeded .iso files live."
+          Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/pxeforge/isos</Config>
+  <Config Name="Work dir" Target="/var/lib/pxeforge/work" Default="/mnt/user/appdata/pxeforge/work"
+          Mode="rw" Description="Settings, NFS state, and runtime scratch. Persisted across restarts."
+          Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/pxeforge/work</Config>
+  <Config Name="SMB share root" Target="/var/lib/pxeforge/smb" Default="/mnt/user/appdata/pxeforge/smb"
+          Mode="rw" Description="Where extracted Windows install media lives. Only used when Windows toggle is on."
+          Type="Path" Display="advanced" Required="false" Mask="false">/mnt/user/appdata/pxeforge/smb</Config>
+  <Config Name="Public IP" Target="PXEFORGE_PUBLIC_IP" Default=""
+          Mode="" Description="IP advertised to PXE clients. Leave blank to auto-detect; set explicitly on multi-homed Unraid hosts."
+          Type="Variable" Display="always" Required="false" Mask="false"></Config>
+  <Config Name="Log filter" Target="PXEFORGE_LOG" Default="info,pxeforge=debug"
+          Mode="" Description="tracing-subscriber EnvFilter expression."
+          Type="Variable" Display="advanced" Required="false" Mask="false">info,pxeforge=debug</Config>
+</Container>