93 lines
2.6 KiB
Markdown
93 lines
2.6 KiB
Markdown
# Runner Images (NixOS)
|
|
|
|
This repo exports reproducible NixOS runner configurations via flake outputs:
|
|
|
|
- `nixosConfigurations.ec-runner-aarch64`
|
|
- `nixosConfigurations.ec-runner-x86_64`
|
|
- `nixosConfigurations.ec-runner-aarch64-netboot`
|
|
- `nixosConfigurations.ec-runner-x86_64-netboot`
|
|
- `nixosConfigurations.ec-runner-x86_64-iso`
|
|
- `nixosConfigurations.ec-runner-aarch64-sdimage`
|
|
|
|
The runner OS exposes this repo's flake source inside the system at:
|
|
|
|
- `/etc/every-channel/flake`
|
|
|
|
This allows a runner to self-build and verify artifacts from the same flake definition.
|
|
|
|
## Read-Only Root + tmpfs Writes
|
|
|
|
The base runner profile enables an initrd overlay that:
|
|
|
|
- remounts the real `/` read-only, and
|
|
- provides a tmpfs-backed writable overlay upperdir.
|
|
|
|
For reliable upgrades and operation, mount persistent filesystems for:
|
|
|
|
- `/boot` (so new boot entries persist)
|
|
- `/nix` (so store contents persist across reboots)
|
|
- `/var` or selected `/var/lib/*` paths (for any state you care about)
|
|
|
|
## Build (OrbStack / Linux)
|
|
|
|
These commands should be run inside a Linux environment with Nix enabled (e.g. OrbStack VM).
|
|
|
|
Build netboot artifacts (iPXE/PXE):
|
|
|
|
```sh
|
|
nix build .#nixosConfigurations.ec-runner-aarch64-netboot.config.system.build.netboot
|
|
```
|
|
|
|
Build an installer ISO (x86_64):
|
|
|
|
```sh
|
|
nix build .#nixosConfigurations.ec-runner-x86_64-iso.config.system.build.isoImage
|
|
```
|
|
|
|
Build an aarch64 SD image:
|
|
|
|
```sh
|
|
nix build .#nixosConfigurations.ec-runner-aarch64-sdimage.config.system.build.sdImage
|
|
```
|
|
|
|
## CI Deploy (Forgejo Releases)
|
|
|
|
Boot images can be built and published from CI via:
|
|
|
|
- `.forgejo/workflows/deploy-runner-images.yml`
|
|
|
|
Triggers:
|
|
|
|
- Manual: `workflow_dispatch`
|
|
- Tags: `boot-v*` (for example `boot-v2026.02.28`)
|
|
|
|
Manual inputs (all optional):
|
|
|
|
- `release_tag` (defaults to `boot-<short-sha>`)
|
|
- `publish_release` (`true`/`false`, default `true`)
|
|
- `build_x86_64_netboot` (`true`/`false`, default `true`)
|
|
- `build_x86_64_iso` (`true`/`false`, default `true`)
|
|
|
|
Published assets are attached to the resolved Forgejo release tag and include:
|
|
|
|
- x86_64 netboot bundle (`kernel`, `initrd`, `netboot.ipxe`) as `.tar.gz`
|
|
- x86_64 installer `.iso`
|
|
- `SHA256SUMS.txt`
|
|
|
|
Notes:
|
|
|
|
- CI image publish is disabled on the Codeberg mirror host.
|
|
- Current CI scope is x86_64 targets; aarch64 image builds remain local/manual unless an aarch64-capable runner is added.
|
|
- For multi-NUC PXE rollout on Unifi networks, use `docs/NUC_UNIFI_NETBOOT.md`.
|
|
|
|
## Outputs
|
|
|
|
After building, artifacts will be in `./result` (a symlink into the Nix store).
|
|
|
|
Common netboot outputs include:
|
|
|
|
- `kernel`
|
|
- `initrd`
|
|
- `netboot.ipxe`
|
|
|
|
Exact filenames may vary across NixOS releases.
|