every.channel/docs/RUNNER_IMAGES.md

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

It also exports reusable NixOS modules:

• nixosModules.ec-runner
• nixosModules.ec-node
• nixosModules.ec-netboot (persistent HTTP/TFTP netboot stage+serve service)

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):

nix build .#nixosConfigurations.ec-runner-aarch64-netboot.config.system.build.netboot

Build an installer ISO (x86_64):

nix build .#nixosConfigurations.ec-runner-x86_64-iso.config.system.build.isoImage

Build an aarch64 SD image:

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.