From 429c0fea134e4cf30cc96736c2199fbc87ec64ca Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 13:59:19 -0500 Subject: [PATCH 1/7] docs(ci-tooling): stop pinning a literal install-action SHA in the examples The documented taiki-e/install-action SHA went stale the next time the workflows repinned. Show the pin format with a placeholder and point at build.yml for the current value, which the prose already told readers to check. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ci-tooling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/skills/ci-tooling.md b/docs/skills/ci-tooling.md index 909ccf93..f6dd8de5 100644 --- a/docs/skills/ci-tooling.md +++ b/docs/skills/ci-tooling.md @@ -29,8 +29,8 @@ metadata: Every `uses:` line must reference a full commit SHA. Never use `@v2` or `@main`. ```yaml -# correct -- uses: taiki-e/install-action@b6b84cf49ebfe0176417bdce007c624f0db37f20 # v2 +# correct (see build.yml for the current pinned SHA) +- uses: taiki-e/install-action@ # v2 # wrong — mutable tag, supply-chain risk - uses: taiki-e/install-action@v2 @@ -48,7 +48,7 @@ Pin the tool version too, not only the action SHA. Without `@`, a binary chosen by an upstream release rather than by a commit in this repo. ```yaml -- uses: taiki-e/install-action@b6b84cf49ebfe0176417bdce007c624f0db37f20 # v2 +- uses: taiki-e/install-action@ # v2 — see build.yml for the current pin with: tool: just@1.58.0 ``` From 05a81ea9dda5c3a1eb8d58b7432553751d25f503 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 13:59:29 -0500 Subject: [PATCH 2/7] docs(factory-integration): drop the podman-as-sysext claim No podman sysext exists or is planned; the only container runtime we ship is containerd, inside the opt-in kubeadm sysext. Say that instead of implying podman (and other runtimes) ship as optional sysexts. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/factory-integration.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/skills/factory-integration.md b/docs/skills/factory-integration.md index 8db72aa2..3281b3e5 100644 --- a/docs/skills/factory-integration.md +++ b/docs/skills/factory-integration.md @@ -29,7 +29,6 @@ The factory pattern is broader than a single host: a downstream CI lab or OS fac │ Core server OS: DDI-first, image-updated │ │ • systemd-sysupdate for atomic A/B updates │ │ • systemd-sysext for optional layers (k0s, extensions) │ -│ • container runtimes as systemd-sysexts │ └─────────────────────────────────────────────────────────────┘ ``` @@ -47,8 +46,10 @@ See [k0s-sysext.md](k0s-sysext.md) for details. ## Workloads are containers The workloads the factory tests and ships live in other repositories or image -pipelines. Container runtimes ship as optional `systemd-sysext`s rather than in -the base /usr image (hard rule 4 forbids container runtimes in the base image). +pipelines. No container runtime ships in the base /usr image (hard rule 4); +the only runtime we ship is containerd, inside the opt-in kubeadm sysext (see +[kubeadm-sysext.md](kubeadm-sysext.md)). Everything else runs in system +containers or in the workload images themselves. > Bluefin Server is the factory floor; optional workloads and variant images run on that floor. @@ -60,7 +61,7 @@ the base /usr image (hard rule 4 forbids container runtimes in the base image). | Atomic, rollback-capable updates | Image-based A/B updates via `systemd-sysupdate`; diskless nodes update by rebooting | | Minimal attack surface / lean base OS | Verity-sealed read-only /usr with bash; optional tools as sysexts | | Kubernetes control plane on every node | k0s delivered as `systemd-sysext` | -| Container workloads | `podman` (and other runtimes) as optional `systemd-sysext`s | +| Container workloads | containerd via the opt-in kubeadm sysext; anything else runs in system containers | | Signed, verifiable release artifacts | Signed UKIs + `SHA256SUMS` signed in-element, verified against `/etc/systemd/import-pubring.pgp` | ## SSH and Remote Diagnostics From 00b26a57ec3277fbb4e885e5dff44150350ea870 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 13:59:44 -0500 Subject: [PATCH 3/7] docs: one canonical source for the signing keys and the release publish Hard rule 6. The sysupdate-signing.asc / import-pubring.pgp pair, the gen-dev-keys behaviour, and the CI secrets were restated in ddi-installer-build.md, and the release-publishes-as-is fact was restated in both build and architecture skills. Keep the key inventory and gen-dev-keys in secure-boot-keys.md, the release-signing key in systemd-sysupdate-verification.md, and the publish contract in the ci-tooling.md release job; the build skill keeps only the rotation-needs-a-new-image-version rationale and points at the rest. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ddi-installer-build.md | 31 +++++++------------ docs/skills/systemd-sysupdate-verification.md | 10 +++--- 2 files changed, 15 insertions(+), 26 deletions(-) diff --git a/docs/skills/ddi-installer-build.md b/docs/skills/ddi-installer-build.md index 529ac4da..9a38a091 100644 --- a/docs/skills/ddi-installer-build.md +++ b/docs/skills/ddi-installer-build.md @@ -54,17 +54,13 @@ just publish-oci :30500/bluefin-server dist/diskless 1 # plain H Every image build signs: the UKIs and systemd-boot with DB, kernel modules with the module signing certificate, and the release `SHA256SUMS` with the -image signing key. `build-image` (and `validate`) depends on `gen-dev-keys`, -which generates throwaway keys in `files/boot-keys/` (gitignored) on first -run: PK/KEK/DB, the module certificate, and the `sysupdate-signing.asc` / -`import-pubring.pgp` pair. Keys are kept unless `--force` is given, and a -partial set (a file of a pair or of the boot set missing or empty) is an error -rather than something to fill in. CI builds -on `main` unpack the `BOOT_KEYS_TARBALL` secret, write `SYSUPDATE_SIGNING_KEY` -to `files/boot-keys/sysupdate-signing.asc`, and copy the committed release -keyring `files/os/sysupdate-keys/import-pubring.gpg` to -`files/boot-keys/import-pubring.pgp`; pull requests get throwaway keys and -their images are never published. +image signing key. What each key is, where it lives, what `just gen-dev-keys` +generates (throwaway keys in the gitignored `files/boot-keys/`, kept unless +`--force`, a partial set is an error), and how CI supplies the real keys: +[secure-boot-keys.md](secure-boot-keys.md). The release-signing half +(`sysupdate-signing.asc` / `import-pubring.pgp`, the committed +`files/os/sysupdate-keys/import-pubring.gpg`, and rotation): +[systemd-sysupdate-verification.md](systemd-sysupdate-verification.md). **Rotating any key needs a new `image-version`.** Every key ends up in the image bits: DB signs the UKIs and systemd-boot, the module certificate is @@ -72,12 +68,8 @@ built into the kernel, and `import-pubring.pgp` ships in `/usr`. An image version names one immutable set of bits, and `systemd-sysupdate` only installs a version newer than the one it runs, so rebuilding the same version with new keys publishes different bits under a released name and never -reaches nodes already on it. Rotate keys (`just gen-dev-keys --force`, or new -CI secrets), then `just set-version` to a version that sorts higher before -building. Nodes also need the new Secure Boot keys enrolled and, for the -image signing key, the new keyring; see -"Rotating the Signing Key" in -[systemd-sysupdate-verification.md](systemd-sysupdate-verification.md). +reaches nodes already on it. Rotate keys, then `just set-version` to a +version that sorts higher before building. ## Reproducible builds @@ -204,9 +196,8 @@ projects: `.github/workflows/build.yml` runs `just validate`, exports the image set (already carrying its signed `SHA256SUMS(.gpg)`), runs the QEMU boot test, and -on `main` publishes `dist/diskless/` as-is: an immutable GitHub Release tagged -`v` plus an ORAS OCI artifact at -`ghcr.io//bluefin-server:,latest`. One version is published +on `main` publishes `dist/diskless/` as-is (see the `release` job in +[ci-tooling.md](ci-tooling.md)). One version is published exactly once; creating an existing tag fails rather than overwriting assets nodes may already trust. diff --git a/docs/skills/systemd-sysupdate-verification.md b/docs/skills/systemd-sysupdate-verification.md index b59ea5ab..43f51780 100644 --- a/docs/skills/systemd-sysupdate-verification.md +++ b/docs/skills/systemd-sysupdate-verification.md @@ -163,9 +163,8 @@ Use `--type spdxjson` to get the SBOM attestation instead. committed. On release builds CI copies it to `files/boot-keys/import-pubring.pgp`. - `files/boot-keys/sysupdate-signing.asc` / `import-pubring.pgp` — the signing - key and public keyring for a build (gitignored). Locally `just gen-dev-keys` - generates a dev key; on main CI writes them from the `SYSUPDATE_SIGNING_KEY` - secret plus the committed release keyring. + key and public keyring for a build (gitignored). Where they come from + locally and in CI: [secure-boot-keys.md](secure-boot-keys.md). - `elements/bluefin-server/os-sysupdate-keys.bst` — installs `files/boot-keys/import-pubring.pgp` as `/etc/systemd/import-pubring.pgp`. - `files/os/sysupdate.d/*.transfer` and the k0s component directory @@ -204,9 +203,8 @@ Use `--type spdxjson` to get the SBOM attestation instead. trust updates signed by the key in their keyring, so plan the rotation around a release boundary. -For a throwaway local signing key, `just gen-dev-keys` writes -`files/boot-keys/sysupdate-signing.asc` and `files/boot-keys/import-pubring.pgp` -on its own; no manual gpg step is needed. +For a throwaway local signing key, `just gen-dev-keys` writes the pair on its +own; see [secure-boot-keys.md](secure-boot-keys.md). ## Common Gotchas From 3c6d9aaa4c0a9d066487aea09b03cec761c23607 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 13:59:52 -0500 Subject: [PATCH 4/7] docs(gap-analysis-distros): trim the sources list to docs roots Section 2 already links every specific claim inline; section 6 restated the same URLs. Keep one link per distro documentation root. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/gap-analysis-distros.md | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/docs/skills/gap-analysis-distros.md b/docs/skills/gap-analysis-distros.md index ce1b0b00..91f786ac 100644 --- a/docs/skills/gap-analysis-distros.md +++ b/docs/skills/gap-analysis-distros.md @@ -147,31 +147,18 @@ These gaps drive the priorities in [architecture-roadmap.md](architecture-roadma ### Upstream distribution documentation +Specific claims carry inline links in section 2. Documentation roots: + - Ubuntu Server / autoinstall / cloud-init - - - - - - - - - -- Talos Linux - - - - - - - - -- Flatcar Container Linux - - - - - - +- Talos Linux — +- Flatcar Container Linux — - Fedora CoreOS / rpm-ostree / Zincati - - - - - - - - - - - - + - + - - - - ### systemd reference From b81d8cc8e31cd53e979f0371b81011030d157938 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 14:00:05 -0500 Subject: [PATCH 5/7] docs: extract the offline USB installer into its own skill The installer section from #264/#268/#277 lived inside ddi-installer.md. Move it to docs/skills/usb-installer.md covering the image layout and boot flow, unattended installs through the systemd.unit-dropin.systemd-sysinstall.service credential, the firstboot root-password prompt drop-in, and provisioning the installed disk from its ESP; ddi-installer.md keeps a one-line pointer and a short artifact table row. ddi-installer.md's key and release paragraphs also collapse to pointers (the dedupe from the previous commit). Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ddi-installer.md | 44 +++------------ docs/skills/usb-installer.md | 100 +++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 36 deletions(-) create mode 100644 docs/skills/usb-installer.md diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index 7a8daaf2..ba6f414b 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -37,15 +37,14 @@ GPT partition label with room to spare): | `bluefin-server-.efi` | Disk UKI (installed nodes); also the sysupdate source for `$BOOT`. | | `bluefin-server-netboot_.efi` | Netboot UKI (diskless nodes); the UEFI HTTP boot / PXE target. | | `bluefin-server-netboot_.esp.raw` | Netboot ESP image: signed systemd-boot, the netboot UKI, and Secure Boot key enrollment payloads. Write it to a USB stick to boot diskless without HTTP boot. | -| `bluefin-server-installer_.raw` | Offline USB installer: the same usr + verity images (labelled `bluefin-installer-usr` / `bluefin-installer-usr-verity`) plus an ESP with signed systemd-boot, the installer UKI, key enrollment payloads, and the disk UKI + install-time `repart.d` under `bluefin/`. Write it to a USB stick to install without a network. | +| `bluefin-server-installer_.raw` | Offline USB installer; write to a stick to install without a network. See [usb-installer.md](usb-installer.md). | | `zfs_.raw.zst` / `kubestellar_.raw.zst` / `kubeadm_.raw.zst` | Opt-in sysext assets locked to this image version; installed nodes fetch them through the `zfs` / `kubestellar` / `kubeadm` sysupdate features. | | `k0s-.raw.zst` | Opt-in k0s sysext asset, on its own version axis. | | `efi-keys/` | PK/KEK/db enrollment payloads. | | `SHA256SUMS` / `SHA256SUMS.gpg` | One manifest over every file above, signed in-element with `files/boot-keys/sysupdate-signing.asc`; the image trusts the matching `import-pubring.pgp` (see `systemd-sysupdate-verification.md`). | -A release is this directory published as-is: a GitHub Release `v` plus an -ORAS OCI artifact `ghcr.io//bluefin-server:,latest` (one layer per -file, artifact type `application/vnd.projectbluefin.server.release.v1`). +A release publishes this directory as-is (GitHub Release `v` plus an ORAS +OCI artifact); see the `release` job in [ci-tooling.md](ci-tooling.md). `just publish-oci REF [DIR] [PLAIN_HTTP]` pushes the same artifact locally. The /usr image itself is built by `oci/bluefin-server-usr.bst` with an offline @@ -64,10 +63,9 @@ signed with DB, so Secure Boot locks those command lines. `lockdown=integrity` is always on. `os-sd-boot-signed.bst` signs systemd-boot with the same DB key so installed disks and the netboot ESP get a loader firmware accepts. -Dev keys come from `just gen-dev-keys` (throwaway keys in the gitignored -`files/boot-keys/`, including the `sysupdate-signing.asc` / -`import-pubring.pgp` pair that signs and verifies `SHA256SUMS`); CI builds on -main use the `BOOT_KEYS_TARBALL` and `SYSUPDATE_SIGNING_KEY` secrets. +The signing keys (dev vs CI, and the pair that signs and verifies +`SHA256SUMS`): [secure-boot-keys.md](secure-boot-keys.md) and +[systemd-sysupdate-verification.md](systemd-sysupdate-verification.md). ### Diskless (netboot UKI) @@ -132,34 +130,8 @@ installed disk is identical whichever path installed it. No shell installer. ### From the USB installer (offline) -```bash -sudo dd if=bluefin-server-installer_.raw of=/dev/ bs=4M conv=fsync status=progress -``` - -```text -firmware -> systemd-boot -> bluefin-server-installer_.efi - -> /usr from the stick's bluefin-installer-usr partition (dm-verity, usrhash=) - -> tmpfs root, systemd.unit=system-install.target - -> systemd-sysinstall.service on the monitor (/dev/console = tty0) -``` - -The installer UKI finds its /usr by partition label, not by the -usrhash-derived UUIDs. Those UUIDs belong to installed usr slots, so an -existing Bluefin install (including the disk being overwritten) is never opened -as the installer's /usr, and an installed node booted with the stick still -plugged in never opens the stick's usr. `run-bluefin-installer.mount` mounts -the stick's ESP (`bluefin-installer`) at `/run/bluefin/installer`; the -`systemd-sysinstall.service` drop-in passes -`--definitions=/run/bluefin/installer/bluefin/repart.d` and -`--kernel=${BLUEFIN_INSTALL_KERNEL}` (the disk UKI, named by the installer -UKI's `systemd.setenv=`). The disk UKI sits outside `EFI/Linux` on the stick so -systemd-boot never offers it there. sysinstall prompts for the target disk, -erasing it, and confirmation, then reboots; remove the stick when it does. - -Secure Boot: the stick's systemd-boot and UKIs are signed with the project DB -key. On bare metal put the firmware into Setup Mode and pick the enrollment -entry in the systemd-boot menu (`secure-boot-enroll if-safe` only -auto-enrolls in VMs), or turn Secure Boot off. +See [usb-installer.md](usb-installer.md) — the offline installer image, its +boot flow, unattended installs, and install-time provisioning. ### From a diskless node diff --git a/docs/skills/usb-installer.md b/docs/skills/usb-installer.md new file mode 100644 index 00000000..4100a19b --- /dev/null +++ b/docs/skills/usb-installer.md @@ -0,0 +1,100 @@ +--- +name: usb-installer +description: The offline USB installer bluefin-server-installer_.raw. Load when working on the installer image, its systemd-sysinstall drop-in, unattended installs via systemd.unit-dropin credentials, or install-time provisioning from the ESP. +metadata: + type: reference + status: stable + last_updated: "2026-09-29" + context7-sources: + - /systemd/systemd +--- +# Offline USB Installer + +`bluefin-server-installer_.raw` is the offline USB installer in the +release set: the same usr and usr-verity images as the OS DDI (labelled +`bluefin-installer-usr` / `bluefin-installer-usr-verity`) plus an ESP with +signed systemd-boot, the installer UKI, the Secure Boot key enrollment +payloads, and the disk UKI + install-time `repart.d` under `bluefin/`. Write +it to a USB stick to install without a network: + +```bash +sudo dd if=bluefin-server-installer_.raw of=/dev/ bs=4M conv=fsync status=progress +``` + +## Boot flow + +```text +firmware -> systemd-boot -> bluefin-server-installer_.efi + -> /usr from the stick's bluefin-installer-usr partition (dm-verity, usrhash=) + -> tmpfs root, systemd.unit=system-install.target + -> systemd-sysinstall.service on the monitor (/dev/console = tty0) +``` + +The installer UKI finds its /usr by partition label, not by the +usrhash-derived UUIDs. Those UUIDs belong to installed usr slots, so an +existing Bluefin install (including the disk being overwritten) is never +opened as the installer's /usr, and an installed node booted with the stick +still plugged in never opens the stick's usr. The installer is offline: its +initrd masks `systemd-networkd-wait-online`, as the disk UKI already does. + +`run-bluefin-installer.mount` mounts the stick's ESP (`bluefin-installer`) at +`/run/bluefin/installer` (with `fmask=0133,dmask=0022`, so systemd-repart does +not warn about executable definition files). The +`systemd-sysinstall.service.d/10-bluefin-installer.conf` drop-in passes +`--definitions=/run/bluefin/installer/bluefin/repart.d` and +`--kernel=${BLUEFIN_INSTALL_KERNEL}` (the disk UKI, named by the installer +UKI's `systemd.setenv=`). The disk UKI sits outside `EFI/Linux` on the stick +so systemd-boot never offers it there. sysinstall prompts for the target +disk, erasing it, and confirmation, then reboots; remove the stick when it +does. + +The installed disk is identical to one a diskless node installs: stock +`systemd-sysinstall` with the layout from `files/os/repart.d/` (see +[ddi-installer.md](ddi-installer.md), "Installing to disk"). + +## Unattended installs + +`systemd-sysinstall` is interactive on `/dev/console`. To make an install +unattended, pass a `systemd.unit-dropin.systemd-sysinstall.service` system +credential (SMBIOS type 11, QEMU fw_cfg, or a `.cred` file in +`/loader/credentials/` on the stick's ESP). It lands as `50-credential.conf`, +after the image's `10-bluefin-installer.conf`, and re-runs that drop-in's +`ExecStart=` with the target disk and `--erase=yes --confirm=no +--variables=yes` appended, plus `StandardInput=null` so any leftover prompt +fails instead of hanging. `scripts/dogfood-installer.sh` drives exactly this +path in QEMU and is the reference for the drop-in contents. + +## First-boot prompt + +Root ships locked as `!unprovisioned`, which `systemd-firstboot` reads as +"root not configured yet"; upstream's `--prompt-root-password` would block +the installer's console on a password prompt. The +`systemd-firstboot.service.d/10-bluefin-no-root-prompt.conf` drop-in removes +only that prompt: the `passwd.hashed-password.root` / +`passwd.plaintext-password.root` credentials still apply, and without one +root stays locked. See [tpm2-credential-sealing.md](tpm2-credential-sealing.md). + +## Credentials and the ESP + +The installer needs no login: `systemd-sysinstall` runs on the console. It +does not carry the installer's credentials over to the installed disk, so +provision the installed node by placing encrypted `.cred` files in +`/loader/credentials/` on the installed disk's ESP before its first boot +(details in [tpm2-credential-sealing.md](tpm2-credential-sealing.md)). + +## Secure Boot + +The stick's systemd-boot and UKIs are signed with the project DB key. On bare +metal put the firmware into Setup Mode and pick the enrollment entry in the +systemd-boot menu (`secure-boot-enroll if-safe` only auto-enrolls in VMs), or +turn Secure Boot off. + +## See also + +- [ddi-installer.md](ddi-installer.md) — boot, install, and update architecture. +- [ddi-installer-build.md](ddi-installer-build.md) — build and dogfood + (`just dogfood-installer`). +- [tpm2-credential-sealing.md](tpm2-credential-sealing.md) — first-boot + credentials and ESP credential files. +- [secure-boot-keys.md](secure-boot-keys.md) — the keys that sign the stick. +- [CONTEXT.md](../../CONTEXT.md) — canonical project domain glossary (Installer). From 5072af1a7111f2d237e5e50277f6781837dce0a5 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 14:00:14 -0500 Subject: [PATCH 6/7] docs: route booty-integration, secure-boot-keys and usb-installer All three skill files existed (or were just added) without a row in the lazy-load routing table. List them in docs/skills/index.md and in the AGENTS.md skill routing table. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 3 +++ docs/skills/index.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index eda78e27..1934dcdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,6 +64,8 @@ All local `just` targets run BuildStream inside the FSDK `bst2` container via `j | Task | Skill | |---|---| | Boot / install / update architecture and local build + dogfood | [`docs/skills/ddi-installer.md`](docs/skills/ddi-installer.md), [`docs/skills/ddi-installer-build.md`](docs/skills/ddi-installer-build.md) | +| Offline USB installer (unattended installs, install-time provisioning) | [`docs/skills/usb-installer.md`](docs/skills/usb-installer.md) | +| Network boot at scale (Booty: HTTP boot, per-node Ignition) | [`docs/skills/booty-integration.md`](docs/skills/booty-integration.md) | | Diskless boot failures, RAM sizing, node logs, Ignition configs | [`docs/skills/diskless-troubleshooting.md`](docs/skills/diskless-troubleshooting.md) | | Factory role, k0s sysext rationale, lab integration | [`docs/skills/factory-integration.md`](docs/skills/factory-integration.md) | | Work with `systemd-sysext` / `systemd-confext` | [`docs/skills/systemd-sysext-extensions.md`](docs/skills/systemd-sysext-extensions.md) | @@ -72,6 +74,7 @@ All local `just` targets run BuildStream inside the FSDK `bst2` container via `j | Update the FSDK pin / versioning | [`docs/skills/bump-fsdk-version.md`](docs/skills/bump-fsdk-version.md) | | CI workflows, action SHA pinning | [`docs/skills/ci-tooling.md`](docs/skills/ci-tooling.md) | | Release signing / sysupdate trust | [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md) | +| Secure Boot / module / signing key inventory, rotation, CI secrets | [`docs/skills/secure-boot-keys.md`](docs/skills/secure-boot-keys.md) | | Node access (root / SSH) and credential sealing with TPM2 | [`docs/skills/tpm2-credential-sealing.md`](docs/skills/tpm2-credential-sealing.md) | | System containers (`machinectl`) | [`docs/skills/system-containers.md`](docs/skills/system-containers.md) | | Cut bloat / avoid over-engineering | [`docs/skills/avoid-over-engineering.md`](docs/skills/avoid-over-engineering.md) | diff --git a/docs/skills/index.md b/docs/skills/index.md index ccd03070..c9be9f6f 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -24,6 +24,7 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w |---|---|---| | [`avoid-over-engineering.md`](avoid-over-engineering.md) | Cutting scope, deleting code, resisting bloat | Rules and red flags for keeping solutions small. | | [`architecture-roadmap.md`](architecture-roadmap.md) | Future architecture direction, long-lead design | Roadmap for systemd-native architecture work. | +| [`booty-integration.md`](booty-integration.md) | HTTP boot, iPXE chainloading, per-node Ignition, kubeadm worker provisioning via Booty | How the Booty network boot server serves releases to nodes. | | [`bump-fsdk-version.md`](bump-fsdk-version.md) | Pinning or retagging the FSDK junction | Update the pinned FSDK release and derived tags. | | [`ci-tooling.md`](ci-tooling.md) | GitHub Actions, workflow SHA pinning, CI conventions | CI conventions and release pipeline rules. | | [`ddi-installer-build.md`](ddi-installer-build.md) | Building and dogfooding the image set | Local build, export, and QEMU dogfood workflow. | @@ -34,11 +35,13 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w | [`kubeadm-sysext.md`](kubeadm-sysext.md) | Joining a kubeadm cluster, kubelet/containerd sysext, Kubernetes kernel options | Build and runtime contract for the kubeadm worker sysext. | | [`k0s-sysext-ops.md`](k0s-sysext-ops.md) | Operating k0s or the KubeStellar appliance on Bluefin Server | Runtime operation and troubleshooting for the k0s and KubeStellar sysexts. | | [`k0s-sysext.md`](k0s-sysext.md) | Building the k0s sysext | BuildStream element and publish steps for the k0s sysext. | +| [`secure-boot-keys.md`](secure-boot-keys.md) | Rotating signing keys, setting up CI secrets, debugging signature verification | Key inventory, `gen-dev-keys`, CI secrets, and rotation. | | [`skill-improvement.md`](skill-improvement.md) | Adding, splitting, or refactoring skills | Meta-skill that owns the documentation loop. | | [`system-containers.md`](system-containers.md) | Running `systemd-nspawn` toolboxes | System container operation with `machinectl`. | | [`systemd-sysext-extensions.md`](systemd-sysext-extensions.md) | Optional layers via `systemd-sysext` / `systemd-confext` | Extension identity, loading, and version matching. | | [`systemd-sysupdate-verification.md`](systemd-sysupdate-verification.md) | Image-based A/B updates and signed manifests | Release signing, `systemd-sysupdate`, and trust model. | | [`tpm2-credential-sealing.md`](tpm2-credential-sealing.md) | First-boot credentials, root/SSH node access, TPM2 sealing | Provisioning credentials, node access, and sealing with `systemd-creds`. | +| [`usb-installer.md`](usb-installer.md) | The offline USB installer image, unattended installs, install-time provisioning | `bluefin-server-installer_.raw` boot flow, sysinstall drop-in, ESP credentials. | ## Standing facts From 7de77208c019bf86e38f82a446977237cd85413a Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 14:00:25 -0500 Subject: [PATCH 7/7] docs(readme): add a Download a release section Point evaluators at the published artifacts before the build-oriented quick start: the GitHub Release and OCI artifact, which file covers a diskless USB boot versus an offline install versus Booty network boot, and where the verification steps live. Deferred from #276. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 5e6b89bd..013fba85 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,18 @@ Bluefin Server is currently in **Alpha**: > **Remote diagnostics:** OpenSSH is installed for on-demand diagnostics, but is disabled by default via systemd presets. It can be started manually with `systemctl start sshd` when remote access is needed. See [`docs/skills/factory-integration.md`](docs/skills/factory-integration.md). +## Download a release + +Each push to `main` publishes an immutable [GitHub Release](https://github.com/projectbluefin/server/releases) tagged `v` and the same file set as an OCI artifact at `ghcr.io/projectbluefin/bluefin-server` (tags `` and `latest`). Which file you want: + +| File | Use it for | +|---|---| +| `bluefin-server-netboot_.esp.raw` | Written to a USB stick, boots a node diskless (pulls the OS into RAM over HTTP). | +| `bluefin-server-installer_.raw` | Written to a USB stick, boots into `systemd-sysinstall` for an offline install to disk. | +| everything else | [Booty](https://github.com/jeefy/booty) syncs the whole release and serves it for network boot at scale. | + +Verify the download against the GPG-signed `SHA256SUMS` before use; the release public keyring is [`files/os/sysupdate-keys/import-pubring.gpg`](files/os/sysupdate-keys/import-pubring.gpg), and the verification and attestation steps are in [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md). + ## Quick start You need only `podman` and [`just`](https://github.com/casey/just). BuildStream runs inside the FSDK `bst2` container, so BuildStream is not installed locally.