diff --git a/docs/decisions/0043-release-formats.md b/docs/decisions/0043-release-formats.md new file mode 100644 index 0000000..f0db151 --- /dev/null +++ b/docs/decisions/0043-release-formats.md @@ -0,0 +1,372 @@ +# 0043: Release formats + +Date: 2026-10-01 +Status: **decided by the maintainer, 2026-10-01**: Keel publishes two +formats, the ISO and the `.tar.zst`. The decision is under "Decision"; +what was proposed and not taken is under "Resolved". Nothing here is built +except the first fix it depends on (Keel-Linux/buildtasks#16, the +machine-id of the ISO, tracker#24). Decided parts of 0005, 0012, 0016 and +0039 are restated only where this note builds on them. + +The maintainer's requirements, 2026-10-01, before the proposal: + +- Keel releases are published in **every format TurnKey Linux shipped**, + not only the Proxmox `.tar.zst`: the ISO, the VMware formats and the + others; +- **Docker is out** as a format of its own. The project ships system + containers only; +- images are also published as **GitHub Releases** on each appliance + repository. The first was published by hand on 2026-10-01: + [keel-core `testing-19.0-3-step4-20260930`](https://github.com/Keel-Linux/keel-core/releases/tag/testing-19.0-3-step4-20260930), + the `.tar.zst` and its `.sha512`, marked unsigned and not for production. + Uploads happen from the build host or an attended step, **never from the + CI runner**. + +The evidence below led the maintainer to cut the list to two files rather +than rebuild TurnKey's whole set. + +## What TurnKey ships, measured on 2026-10-01 + +Read from `releases.turnkeylinux.org` and `mirror.turnkeylinux.org` (curl, +read only), the TurnKey page "Supported virtualization platforms and build +types" (`www.turnkeylinux.org/docs/builds`) and the `bt-*` scripts of +Keel-Linux/buildtasks, branch `19.x`. + +| Format | Script | Output | Last published by TurnKey | +| --- | --- | --- | --- | +| Hybrid ISO, BIOS and UEFI, live or installed with `tkl-installer` | `bt-iso` (fab's `product.iso`, `isohybrid`), `bin/iso-release` | `turnkey-core-19.0-trixie-amd64.iso` | 19.0, the only 19.0 format published so far | +| Proxmox VE and LXC template | `bt-container` (patches `headless`, `container`: kernel purged) | `debian-12-turnkey-core_18.1-1_amd64.tar.gz` | 18.x | +| OVA, VMware and VirtualBox | `bt-vm`, `bin/vm-bundle` (LVM disk, grub, `ovftool`) | `turnkey-core-15.0-stretch-amd64.ova` | 15.x | +| VMDK in a zip, with a `.vmx` | `bt-vm`, `bin/vm-bundle` | `turnkey-core-15.0-stretch-amd64-vmdk.zip` | 15.x | +| qcow2, OpenStack, headless | `bt-openstack`, `bin/openstack-bundle` (patches `headless`, `cloud`, `openstack`, extlinux) | `turnkey-core-15.0-stretch-amd64-openstack.qcow2` | 15.x | +| Xen domU tarball, headless | `bt-xen` (patches `headless`, `xen`) | `turnkey-core-15.0-stretch-amd64-xen.tar.bz2` | 15.x | +| Docker image | `bt-docker`, `bt-qemu-docker` (`docker push` to Docker Hub) | `turnkey/core` on the Docker index | not on the mirror | +| AWS AMI | `bt-ec2` (registers an AMI in AWS; no file) | an AMI id | through the TurnKey Hub | +| OpenStack AMI style tarball, Open Telekom Cloud qcow2 | `bt-openstack-ami`, `bt-otc` | `-openstack.tar.gz`, `-openstack.qcow2` | not on the mirror | +| Raw disk image (ARM boards) and its qcow2 | `bt-img`, `bt-prepqemu` | `.img.xz`, `.qcow2` | not on the mirror | +| Bootstrap | `bt-bootstrap` | `bootstrap-trixie-amd64.tar.gz` | bookworm (Keel publishes trixie, `docs/releases-host.md`) | + +Also in the tree: `bt-optimized` (runs `bt-vm` and `bt-container`; the +OpenStack, Xen and Docker lines are commented out), `bt-bugfix`, +`bt-bugfix-single` and `bt-iso-patched` (re-release a patched ISO), +`bt-iso-list`, and Keel's own `bt-layer`, `bt-layer-measure` and +`bt-aplinfo`. + +What this shows: **TurnKey itself stopped publishing the VM, OpenStack and +Xen builds after 15.x.** `releases.turnkeylinux.org/turnkey-core/` lists +`.ova`, `-vmdk.zip`, `-openstack.qcow2` and `-xen.tar.bz2` hashes for 14.2 +and 15.0, has no 16.x or 17.x entry, and lists only the ISO and the Proxmox +template for 18.0 and 18.1 (WordPress 18.2 the same); +the `ova/`, `vmdk/`, `xen/` and `openstack/` directories on the mirror are +empty. Their documentation still describes all of them. The code shows the +same age: `bt-vm` knows guest OS ids up to bullseye only and stops with +"vm_guestos could not be determined" on trixie, `bin/vm-bundle` reads the +kernel version with a pattern written for 4.19, and both OVA and VMDK need +`ovftool`, VMware's proprietary tool, which is not in Debian. + +## What Keel publishes today + +- **The Proxmox template** `debian-13-keel-_-_amd64.tar.zst`, + made by `keel assemble` from the layer chain `bt-layer` builds, staged by + `keel-release` (Keel-Linux/apt `lib/release.sh`) in + `/srv/keel-release//`, published by `keel-publish-mirror` (apt + `lib/mirror.sh`) to `mirror.keellinux.org/images/` with a `.sha512` and a + detached `.sha512.asc` (or a `.sha512.UNSIGNED` note). +- **The Proxmox index** `releases.keellinux.org/pve/aplinfo.dat{,.gz,.asc}`, + cumulative (tracker#11), and the release `MANIFEST` and its signature in + `releases.keellinux.org/meta//`. +- **The layers** in `mirror.keellinux.org/layers/` with the `stable` and + `testing` channel pointers of 0016. +- **No ISO and no VM image.** buildtasks has the scripts, but none is wired + into `keel-release`, and every one of them starts from an ISO + (`iso-download`, `tklpatch-extract-iso`) that Keel never built. + +Signing (0005): the release key's signing subkey is on the build host, +passphrase protected; a release is attended because the maintainer types +the passphrase and the agent forgets it after ten minutes. `keel-release` +does everything that needs no key first and signs last, and +`keel-release --sign-only ` signs what is staged without rebuilding. + +## Decision + +### 1. Two formats + +A release of one appliance publishes **two files**, the same root +filesystem in two wrappers: + +| File | Covers | Made by | +| --- | --- | --- | +| `.iso`, hybrid, BIOS and UEFI | VMware, VirtualBox, Proxmox VE virtual machines, Hyper-V, KVM, bare metal: boot it and install with `tkl-installer`, or run it live | `bt-iso` on the build host | +| `.tar.zst` | Proxmox VE containers and LXC, as today; Docker through `docker import` (section 2) | `bt-layer` and `keel assemble` on the build host, as today | + +Nothing else is published: no OVA, VMDK or qcow2 download, no Xen tarball, +no Docker image format, no AMI, no ARM image. TurnKey itself stopped +publishing the VM, OpenStack and Xen builds after 15.x (above), and every +hypervisor among them installs from the ISO. + +Both formats go to **Core and Web** first, since they are what Phases 1 and +3 deliver (tracker#46). The other appliances keep the `.tar.zst` and get +the ISO one by one, each after its first boot was run from that ISO. A +format is never published for an appliance whose first boot was not run in +it. + +### 2. Docker, from the same `.tar.zst` + +`docker import` reads the template as it is: + + docker import debian-13-keel-core_19.0-3_amd64.tar.zst keel/core:19.0-3 + +zstd is read since **Docker Engine 23.0**: its release notes list "Add +support for pulling `zstd` compressed layers" +([moby/moby#41759](https://github.com/moby/moby/pull/41759), in +`pkg/archive`), and `docker import` decompresses through that same +`archive.DecompressStream` (`daemon/images/image_import.go` at `v23.0.0`; +`pkg/archive` in 20.10.24 has no zstd). An older Engine needs +`zstd -d` first and imports the plain `.tar`. + +**The appliance expects systemd as PID 1**, which Docker does not give a +container by default. Two ways to run it: + + docker run -d --name core --privileged --cgroupns=host \ + -v /sys/fs/cgroup:/sys/fs/cgroup:rw \ + --tmpfs /run --tmpfs /run/lock --tmpfs /tmp \ + keel/core:19.0-3 /sbin/init + +or, without `--privileged`, the [Sysbox](https://github.com/nestybox/sysbox) +runtime, which runs systemd in an ordinary container: + + docker run -d --runtime=sysbox-runc --name core keel/core:19.0-3 /sbin/init + +Then `docker exec -it core keel-init` runs the first boot. + +**Said plainly: on Docker, first boot and services are not guaranteed the +way they are on LXC.** Docker manages networking, `/etc/hosts`, +`/etc/resolv.conf` and the hostname itself, which the first boot screens, +`keel network` (0018) and the WireGuard overlay expect to own; nftables, +CrowdSec's bouncer and WireGuard need capabilities and kernel modules a +container may not have; and `--privileged` gives the container the host. +The Docker path is documented and best effort. **Keel's own tests use +system containers only** (LXC, as `docs/ci-cd.md` describes); nothing is +tested on Docker, and a defect seen only there is not a release blocker. + +### 3. AWS and OpenStack: converted locally, later + +Neither file is uploaded to a cloud as it is. The `.tar.zst` is a +container root filesystem: it has no kernel and no boot loader, and both +clouds import virtual machine disks (AWS `ec2 import-image`: VMDK, VHD, +OVA or raw; OpenStack Glance: qcow2, raw or ISO, among others). The ISO +can be installed by hand into a VM there, which stays the manual +alternative. + +The plan is a **local conversion in keel**: `keel assemble --format raw|qcow2` +takes the same layers, adds a kernel, GRUB and a cloud datasource client, +resets the machine identity (section 8), and writes a disk the user +uploads with the cloud's own tools (`aws ec2 import-image`, `openstack image +create`). Keel publishes no cloud image and holds no cloud account. + +**This is its own later phase**, validated on real AWS and OpenStack +accounts before it is announced, and **not built now**. + +### 4. Names + +TurnKey's Proxmox naming, which Keel already publishes and `bt-aplinfo` +parses: + + debian-13-keel-_-_amd64.tar.zst + debian-13-keel-_-_amd64.iso + +`-` is the appliance version and revision from the product's +changelog, as `release_version` reads it (for example `19.0-3`). A testing +build adds `+