max / alloy

Record the distribution decision: builders, not images Decided 2026-07-30. Nobody downloads an Alloy image. Users take the source, configure it, build the ISO on their own machine and write it to a medium. Design and consequences: wiki alloy-distribution, GoingsOn alloy 1372b159. Both docs were promising the opposite. STACK.md said a container image would be published on quay.io/alloy/alloy "when distribution starts", and IMAGE.md carried a registry section and a cosign section written as deferred work rather than as work that is not happening. In a repo that went public this morning, that is the first thing a stranger reads about how to get Alloy, and it was wrong. Most of the mechanism was already here and already agreed with the decision: build-iso.sh builds an installer ISO from a locally-built image, build-image.sh --write does the write with device checks, and 85ee0e6 had already ruled that over-the-air updates are a development-build feature with nothing published to fetch from. What was missing was the docs saying so. Three things fall out and are recorded as the point rather than as side effects. There is no signing story to build, because cosign signs images in a registry and there is no registry; what a user verifies is the source, which git already gives them. There is no GPL source-availability obligation, because that attaches to whoever redistributes the binaries, and the RPMs come to the user from Fedora and Terra rather than from us. And the absence of hosted CI stops being a release gap, though it is still a real gap for validating the Containerfile, which is now written down separately so the two do not get conflated again. The accepted costs are stated in both files rather than left to be discovered: building needs Linux with podman, real disk and a long wall clock, so there is no path to an Alloy ISO from macOS or Windows; and an installed machine never self-updates until the synckit/MNW update service exists, so updating means rebuilding.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Max Johnson <me@maxj.phd> · 2026-07-30 19:58 UTC

Signed with PGP, not checked

Commit: 20e0471118d5a251033613929cee9c2e59297841

Parent: df2eb6e

2 files changed, +22 insertions, -10 deletions

M docs/IMAGE.md +17 -9

			@@ -42,7 +42,7 @@
42	42
43	43		Alloy publishes its source on Make Creative's own platform, for the reason the project holds elsewhere: independence from big-tech-monopoly infrastructure at the layer where users install software, and hosting our own source rather than renting someone's. `astra` is the private mirror and `srht` is a backup remote, not the public face. See `~/Code/CLAUDE.md`, "What each remote is for".
44	44
45		-	Current state: the `mnw` remote is configured but not pushed, so that URL is not live yet. Alloy goes public when there is a manual for a stranger to read.
	45	+	Current state: live since 2026-07-30. The source is the distributed artifact, so this URL is not a courtesy listing, it is where Alloy comes from.
46	46
47	47		### CI: none. Builds are local and native.
48	48
			@@ -50,21 +50,29 @@
50	50
51	51		The image is built by `build/build-image.sh` (disk images, via bootc-image-builder) and `build/build-iso.sh` (the installer ISO) on fw13, against rootful podman. That is the whole build story today, and it is a deliberate consequence of two standing rules rather than an accident: builds are native per architecture and nothing is cross-compiled, and app binaries are never built on the production host.
52	52
53		-	Which means an always-on x86_64 builder is the actual missing piece, not a CI config. astra is always-on but aarch64, and the image is x86_64. fw13 is x86_64 but sleeps aggressively. Until one machine is both, "CI" would be a scheduler with nothing to schedule onto. The Fedora build host meant to replace Pop!_OS on fw13 is where this resolves.
	53	+	An always-on x86_64 builder is still wanted for development. It is no longer between Alloy and other people running it: nothing has to be built centrally for a stranger to install Alloy, because the stranger does the building. astra is always-on but aarch64, fw13 is x86_64 and sleeps aggressively, and the Fedora build host meant to replace Pop!_OS on fw13 is where that resolves whenever it does.
54	54
55		-	### Registry: `quay.io` (deferred until distribution starts)
	55	+	What deleting the sourcehut job actually cost is worth naming rather than glossing: it ran a build-and-lint smoke test on every push, and now nothing validates the Containerfile except someone remembering to build. That gap is real and is independent of distribution.
56	56
57		-	Red Hat's container registry is the intended destination once Alloy has an image worth distributing. Free for public images, ecosystem-coherent with the `quay.io/fedora/fedora-bootc:43` base.
	57	+	### Registry: none, and this is settled rather than deferred
58	58
59		-	Current state: no registry provisioned, and nothing validates the Containerfile except running `build/build-image.sh` by hand. The old sourcehut job did a build-and-lint smoke test on every push; deleting it means that check now happens when someone remembers to build, which is worth naming rather than glossing. When the image is worth distributing, `quay.io/alloy/alloy` gets provisioned with a robot account and whatever builder exists by then grows `sign` and `push` steps.
	59	+	Nothing is published, and nothing will be. Distribution is the builder, not the artifact (decided 2026-07-30). Users take the source, configure it, build the ISO on their own machine, and write it to a medium.
60	60
61		-	Rejected alternatives (for when distribution starts): ghcr.io (source-registry ecosystem mismatch), Docker Hub (pull rate limits, no advantage), self-hosted (real infra commitment, not worth v0 operational load; revisit v2+).
	61	+	This section previously read as "quay.io once there is an image worth distributing", which framed publishing as inevitable and merely early. It is not the plan. `quay.io/alloy/alloy` is not a reserved future address, and the alternatives that were weighed against it (ghcr.io, Docker Hub, self-hosted) are moot rather than rejected.
62	62
63		-	### Signing: cosign (deferred alongside distribution)
	63	+	Three things follow, and they are the point rather than side effects:
64	64
65		-	Once a registry is publishing images, cosign signs them as a build step. Public key published in the Alloy repo. Users verify via `bootc switch --signature-source=<url>`. Nothing to set up until distribution starts.
	65	+	- No signing story to build. cosign signs images in a registry; with no registry there is nothing to sign, no public key to publish, and no private key needing a home. What a user verifies instead is the source, which is what git already gives them.
	66	+	- No source-availability obligation. The image carries a large number of GPL and LGPL projects, and redistributing their binaries would put the GPL-2 §3 / GPL-3 §6 offer on Make Creative. Ship no binaries and it never attaches: users pull RPMs from Fedora and Terra, who discharge their own.
	67	+	- No hosting, no bandwidth, no publish matrix per architecture.
66	68
67		-	The private key needs a home, and "an sr.ht secret" was the old answer, which went out with the sourcehut build. Whatever builds and pushes the image is what needs to hold it; a signing key on a machine that sleeps is a different problem from a signing key in a hosted secret store, and that is another thing the builder decision settles.
	69	+	The accepted cost is that a build takes real time and disk on the user's own machine, and that there is no path to an Alloy ISO from macOS or Windows at all.
	70	+
	71	+	### Updates: only where updates can be fetched
	72	+
	73	+	An installed machine does not reach out unless the medium it was installed from named an update target, which only a development build does. The installer enables `bootc-fetch-apply-updates.timer` when `--update-target` was given and leaves it disabled otherwise, so a locally-built install never polls anything.
	74	+
	75	+	The eventual home for updates a stranger's machine can reach is a service over synckit/MNW, not a public registry. Until that exists, updating means rebuilding and reinstalling, which is the honest description and should be written that way in the manual.
68	76
69	77		## Layer structure
70	78

M docs/STACK.md +5 -1

			@@ -8,7 +8,11 @@
8	8
9	9		ublue relationship: alongside, not downstream. Preserves naming and architectural independence. The "Alloy" name was picked specifically to avoid the ublue "Blue\*" prefix. Tradeoff: no shared image-building infrastructure, so whatever Alloy ships for image composition is on Alloy to build/maintain. Upside: total architectural freedom and a clean brand.
10	10
11		-	Composition strategy: bootc + Containerfile, `FROM quay.io/fedora/fedora-bootc:43`. Source on `makenot.work/git/max/alloy`, built locally and natively by `build/build-image.sh`, published container image on `quay.io/alloy/alloy` when distribution starts. This is the ublue convention (Containerfile, OCI registry) without ublue's base image, which is what "alongside ublue" resolves to in practice. There is no hosted CI: sourcehut's build was deleted rather than left to rot, and an always-on x86_64 builder is the open question. Full delivery strategy in [IMAGE.md](IMAGE.md). Containerfile at the repo root.
	11	+	Composition strategy: bootc + Containerfile, `FROM quay.io/fedora/fedora-bootc:43`. Source on `makenot.work/git/max/alloy`, built locally and natively by `build/build-image.sh`. This is the ublue convention (Containerfile) without ublue's base image, which is what "alongside ublue" resolves to in practice. Full delivery strategy in [IMAGE.md](IMAGE.md). Containerfile at the repo root.
	12	+
	13	+	No image is published, and none will be. Distribution is the builder, not the artifact: you get the source, configure it, build the ISO on your own machine, and write it to a medium. That is decided (2026-07-30) rather than pending, so `quay.io/alloy/alloy` is not a future address, there is no signing story to wait on, and the absence of hosted CI stops being a gap. An always-on x86_64 builder is still wanted for development and is no longer between Alloy and other people running it.
	14	+
	15	+	Two things follow that are easier to read here than to discover. Building needs Linux with podman, real disk, and a long wall clock, so there is no path to an Alloy ISO from macOS or Windows. And an installed machine does not fetch updates: the timer stays disabled unless the medium named an update target, which only a development build does.
12	16
13	17		## Compositor
14	18