README
¶
incusos-builder
incusos-builder builds seeded IncusOS installation media from a YAML config. It is a local CLI alternative to the IncusOS web customizer.
Install
Homebrew cask (macOS)
brew install --cask componere/tap/incusos-builder
incusos-builder --version
Container image
The OCI image supports Linux containers on amd64 and arm64. Set DIGEST
to the published manifest digest, then pull and run that exact image:
DIGEST='sha256:<published-manifest-digest>'
IMAGE="ghcr.io/componere/incusos-builder@${DIGEST}"
docker pull "$IMAGE"
docker run --rm "$IMAGE" --version
Pin the digest when the image must be repeatable.
For Scoop, native Linux repositories, direct archive downloads, and ghd, see
How to install incusos-builder.
Quick start
init and build write into the working directory, so run them in a scratch directory rather than a source checkout:
WORK=$(mktemp -d)
cd "$WORK"
incusos-builder init --no-input
incusos-builder validate -f config.yaml
incusos-builder build -f config.yaml -o incusos.iso
From a source build, set IOB="$PWD/bin/incusos-builder" before cd, then run "$IOB" in place of incusos-builder.
init --no-input writes a starter config for an online iso build targeting x86_64 on channel stable. Interactive init prompts for those image settings instead.
Every seeds: section in the starter config is commented out. Building it unedited succeeds and reports seed_bytes 1024, an empty seed tar, so the installer starts with no seed applied. Uncomment and fill the sections you need before build.
build splices the seed config into a seed-data partition on the installer image. It fetches images from https://images.linuxcontainers.org/os unless --server points at another HTTPS update server or a local mirror directory.
An offline config also produces rescue media, at a path derived from -o. Use --resources-output to override that path. Passing --resources-output for an online config is a usage error and exits 2.
Commands
| Command | Purpose |
|---|---|
init |
Write a starter config.yaml |
validate |
Check a config without fetching images |
build |
Build installation media from a config |
versions |
List available IncusOS releases from the update server |
--json writes a single JSON envelope to stdout instead of human-readable output. See automation for the envelope shape and the exit-code table.
Documentation
The user manual is the MkDocs tree under docs/docs/. Start with that index for the tutorial, how-to guides, reference, and explanations.
Contributing
See CONTRIBUTING.md.
Security
See SECURITY.md.
License
Licensed under Apache-2.0 or MIT, at your option (Apache-2.0 OR MIT).
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
incusos-builder
command
|
|
|
internal
|
|
|
build
Package build is the domain core of incusos-builder: it resolves a release from update-server metadata, probes the acquired image's GPT, renders and splices the seed tar, and orchestrates offline rescue-media construction — all through ports, with no direct network or filesystem side effects.
|
Package build is the domain core of incusos-builder: it resolves a release from update-server metadata, probes the acquired image's GPT, renders and splices the seed tar, and orchestrates offline rescue-media construction — all through ports, with no direct network or filesystem side effects. |
|
cli
Package cli is the incusos-builder command-line surface: the Cobra root, interaction policy, sentinel-to-exit-code mapping, and the output publisher.
|
Package cli is the incusos-builder command-line surface: the Cobra root, interaction policy, sentinel-to-exit-code mapping, and the output publisher. |
|
config
Package config loads an incusos-builder YAML document into a build.Spec.
|
Package config loads an incusos-builder YAML document into a build.Spec. |
|
errdefs
Package errdefs holds the sentinel errors shared across the domain core and the adapters.
|
Package errdefs holds the sentinel errors shared across the domain core and the adapters. |
|
media
Package media implements build.RescueWriter with go-diskfs: iso9660 (Rock Ridge, no Joliet) and GPT+FAT32 raw media labeled RESCUE_DATA.
|
Package media implements build.RescueWriter with go-diskfs: iso9660 (Rock Ridge, no Joliet) and GPT+FAT32 raw media labeled RESCUE_DATA. |
|
media/mocks
Package mocks contains mockery-generated test doubles for the RescueWriter port defined in internal/build.
|
Package mocks contains mockery-generated test doubles for the RescueWriter port defined in internal/build. |
|
seed
Package seed renders the IncusOS seed-data tar byte-compatibly with upstream image-customizer writeSeed.
|
Package seed renders the IncusOS seed-data tar byte-compatibly with upstream image-customizer writeSeed. |
|
testfixture
Package testfixture writes a local-dir update-server mirror for e2e tests.
|
Package testfixture writes a local-dir update-server mirror for e2e tests. |
|
update
Package update is the ImageSource adapter: an HTTPS update-server client and a local-directory source, both exposing verified content-addressed assets through the build.ImageSource port.
|
Package update is the ImageSource adapter: an HTTPS update-server client and a local-directory source, both exposing verified content-addressed assets through the build.ImageSource port. |
|
update/mocks
Package mocks contains mockery-generated test doubles for the ImageSource and VerifiedAsset ports defined in internal/build.
|
Package mocks contains mockery-generated test doubles for the ImageSource and VerifiedAsset ports defined in internal/build. |
|
ux
Package ux implements the build.Reporter port with a fancy Lip Gloss renderer and a plain ASCII renderer behind one constructor.
|
Package ux implements the build.Reporter port with a fancy Lip Gloss renderer and a plain ASCII renderer behind one constructor. |
|
ux/mocks
Package mocks contains mockery-generated test doubles for the Reporter port defined in internal/build.
|
Package mocks contains mockery-generated test doubles for the Reporter port defined in internal/build. |