Lukas GreveandClaude Sonnet 5
67316d9852
Manifest groups get a tier; only `default` is generated (make all TIER=..., --tier). Default: phyllomeos (GNOME + virt-manager) and phyllomeos-headless, Fedora 44, systemd-boot, CPU-agnostic hypervisor ingredient (hypervisor_type: any). guest tier: guest-server, guest-desktop. experimental: biosboot/grub, encrypted, rawhide. Generator clears stale recipes/dishes before writing. build-image.sh: --dish and --tier; deploy.sh: --tier. build-iso.yaml replaced by build-image.yaml: raw images for both editions on the fedora:host runner (TMPDIR=/var/tmp, max-parallel 1), attached with the flattened kickstarts to tagged releases. Live edition no longer built. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
182 lines
9.1 KiB
Markdown
182 lines
9.1 KiB
Markdown
# Kickstart Phyllome OS
|
|
|
|
[Phyllome OS](https://wiki.phyllo.me/phyllomeos/context) uses the [kickstart installation method](https://pykickstart.readthedocs.io/en/latest/kickstart-docs.html#chapter-1-introduction) to deploy itself to a specific target computer or virtual machine by means of kickstart files.
|
|
|
|
Provided that some dependencies are met (`libvirt` is running on your computer, QEMU is installed, etc), one could run the following script to deploy virtual machines, including Phyllome OS itself.
|
|
|
|
- Make the script executable:
|
|
|
|
```
|
|
chmod +x deploy.sh
|
|
```
|
|
|
|
- Execute it and pick a dish when prompted (by default the two Phyllome OS editions; see [Editions and tiers](#editions-and-tiers)). The example below is from an earlier, larger matrix:
|
|
|
|
```
|
|
./deploy.sh
|
|
|
|
Executing: ./deploy/core-count.sh
|
|
System has more than 2 core (nproc --all: 6).
|
|
[...]
|
|
Available files:
|
|
1. desktop_44_standard_grub_gnome
|
|
[...]
|
|
8. desktop_44_standard_grub_gnome_guest-agents
|
|
[...]
|
|
Enter the number of the file you want to select: 8
|
|
You selected: desktop_44_standard_grub_gnome_guest-agents
|
|
|
|
Starting install...
|
|
Retrieving 'vmlinuz' | 16 MB 00:00:00
|
|
Retrieving 'initrd.img' | 161 MB 00:00:05
|
|
Allocating 'virtinst-n0km88yy-vmlinuz' | 16 MB 00:00:00
|
|
Transferring 'virtinst-qxr2jxcb-initrd.img' | 161 MB 00:00:00
|
|
Allocating 'desktop_44_standard_grub_gnome_guest-agents.img' | 10 GB 00:00:00
|
|
Creating domain...
|
|
```
|
|
|
|
`deploy.sh` regenerates the `recipes` and `dishes` (they are build products) before deploying. Pass `--tier guest` to deploy a plain Fedora server or desktop VM on a Phyllome OS host instead.
|
|
After a successfull installation, the virtual machine will shutdown and be ready to use when powered on again.
|
|
|
|
## Editions and tiers
|
|
|
|
The repo ships a recipe to deploy Phyllome OS on a target host, not a general-purpose kickstart collection. Only two dishes are generated by default (Fedora 44, UEFI, systemd-boot, both with hardware support and guest agents so they also run as VMs):
|
|
|
|
| Dish (prefix) | What it is |
|
|
|---|---|
|
|
| `phyllomeos` | Phyllome OS with a GUI (GNOME + virt-manager) |
|
|
| `phyllomeos-headless` | Headless Phyllome OS |
|
|
|
|
Every group in `cook/recipes_manifest.yaml` belongs to a *tier*, and only the requested tier is generated:
|
|
|
|
| Tier | Contents | Build with |
|
|
|---|---|---|
|
|
| `default` | the two editions above | `make all` |
|
|
| `guest` | `guest-server`, `guest-desktop`: Fedora VMs to deploy on a Phyllome OS host | `make all TIER=guest` |
|
|
| `experimental` | single hand-written variants to try new dishes (BIOS/GRUB, encrypted root, rawhide) | `make all TIER=experimental` |
|
|
|
|
`TIER=all` (or `TIER="default guest"`) combines tiers; `deploy.sh` and `build-image.sh` take `--tier`. Lint always covers every tier, so inactive tiers cannot rot. To test a new dish, add one variant (no list-valued matrices) to an `experimental` group.
|
|
|
|
## Building a disk image (no libvirt/virt-install)
|
|
|
|
`deploy.sh` drives a live `virt-install`/libvirt session. If you just want a
|
|
raw or qcow2 disk image — e.g. to hand to another VM manager such as
|
|
wonder-vm via virtpull's `virtpull local ... --wonder-vm NAME` —
|
|
use `build-image.sh` instead. It runs `livemedia-creator --no-virt
|
|
--make-disk` directly on the host, producing a disk image instead of a
|
|
bootable ISO:
|
|
|
|
```
|
|
./build-image.sh [--dish NAME] [--tier TIER] [--as qcow2] [--root-size MiB] [--extra-ks FILE]
|
|
```
|
|
|
|
It picks a dish the same way `deploy.sh` does (or takes `--dish NAME`) and writes the result under
|
|
`./build/`. The `build-image` CI workflow runs it for both default editions on every push to `main`, and on `v*.*.*` tags it attaches the compressed raw images (`.img.xz`) and the flattened kickstart files to the release. Requires `lorax-lmc-novirt` (heavier than `deploy.sh`'s plain
|
|
QEMU/libvirt prerequisites, not installed by
|
|
`deploy/install-prerequisites-on-linux.sh`) and root — the `--no-virt` disk
|
|
install needs real loop-device access (`/dev/loop-control`), which a
|
|
`mock` chroot cannot provide (no live `systemd-udevd` inside it, which
|
|
breaks blivet's device scan) and neither can a rootless container.
|
|
`--root-size` (default 8192 MiB) sizes the root partition, needed because
|
|
livemedia-creator computes the image size up front, unlike virt-install
|
|
which pre-creates the disk at a known size. `--extra-ks FILE` appends
|
|
local content (e.g. a bespoke `user`/`rootpw` override) to the dish before
|
|
building, without touching the tracked ingredients — see the "bespoke
|
|
dish" pattern below; never commit a file used here if it carries real
|
|
credentials.
|
|
|
|
## Repository structure
|
|
|
|
This repository contains such files broken down as:
|
|
|
|
* `cook/ingredients`🥑 🥥 🥭 🥝 🥦 🥬 🥒 🧄: the basic building blocks for assembling Phyllome OS and other derivatives.
|
|
|
|
* `cook/recipes`🧾 🧩: lists of ingredients to compose several editions. **Build product**: generated by `make all`.
|
|
|
|
* `cook/dishes`🥨 🥐 🥖 🥧 🥞 🥯 🧆 🧁: ready-to-consume and standalone kickstart artifacts, which can be used to deploy complete systems. **Build product**: generated by `make all`.
|
|
|
|
Each ingredient represents a feature or a set of integrated features, such as a specific Desktop Environment or a storage configuration.
|
|
|
|
## Development
|
|
|
|
Using a pull request, you can suggest a modification to an existing ingredient or create a new ingredient from scratch. The cooking pipeline is fully data-driven:
|
|
|
|
* `cook/recipes_manifest.yaml` declares which editions (groups) and which variant matrix to build.
|
|
* `cook/recipe_templates.yaml` ("Proteus") wires variant values and flags to ingredient fragments: `base` (always included), `choices` (exactly-one per category), `features` (additive).
|
|
* `make all` (in `cook/`) composes recipes, flattens them into dishes with pykickstart in-process, lints the invariants pykickstart can't check, and validates every dish.
|
|
|
|
### Requirements
|
|
|
|
- `qemu`
|
|
- `libvirt`
|
|
- `virt-install`
|
|
- `pykickstart` (needed to flatten and validate; `pip install -r cook/requirements.txt`)
|
|
|
|
### Example: add a new package and include it into a recipe
|
|
|
|
- Add [Luanti](https://www.luanti.org/), a free and open-source sandbox video game engine formerly known as Minetest, as a standalone ingredient:
|
|
|
|
```
|
|
echo "%packages --exclude-weakdeps # Beginning of the package section. Does not include weak dependencies
|
|
|
|
luanti # Multiplayer infinite-world block sandbox with survival mode
|
|
|
|
%end # End of the packages section" > cook/ingredients/extra-luanti.ks
|
|
```
|
|
|
|
- Wire it as a new optional feature in `cook/recipe_templates.yaml`:
|
|
|
|
```yaml
|
|
features:
|
|
luanti: extra-luanti.ks
|
|
```
|
|
|
|
- Regenerate:
|
|
|
|
```
|
|
cd cook && make all
|
|
```
|
|
|
|
- Every dish that enables the `luanti` feature now contains the new ingredient. To name such dishes distinctly, enable the flag in the manifest, e.g. add `luanti: [true, false]` to a variant list.
|
|
|
|
Alternatively, for a bespoke dish not part of the matrix, append the ingredient directly to an existing recipe and re-flatten it:
|
|
|
|
```
|
|
echo "%include ../ingredients/extra-luanti.ks # Sandbox video game engine" >> cook/recipes/<recipe>.cfg
|
|
cd cook && make generate
|
|
```
|
|
|
|
### Example: create a new edition from the existing list of ingredients
|
|
|
|
- Print the full ingredient inventory derived from the templates:
|
|
|
|
```
|
|
cd cook && make inventory
|
|
```
|
|
|
|
- Define a new group in `cook/recipes_manifest.yaml` with a `tier` (use `experimental` for anything that should not be built by default); the cartesian product of its list values generates one dish per combination, so keep it to a single variant.
|
|
|
|
### Useful targets (in `cook/`)
|
|
|
|
```
|
|
make all # generate the default tier's dishes, lint, and validate
|
|
make all TIER=guest # ... or the guest / experimental / all tiers
|
|
make lint # check the manifest/templates without writing files
|
|
make validate # validate existing dishes
|
|
make inventory # print the ingredient catalog derived from the templates
|
|
make test # run the pytest test suite
|
|
```
|
|
|
|
## FAQ
|
|
|
|
- **I change one ingredient and many dishes are affected** — just run `make all` to regenerate the full matrix; recipes and dishes are derived from the templates, so they cannot drift.
|
|
|
|
- **I want to inspect what a dish contains** — forget `git diff`: generated files are intentionally untracked. Open `cook/recipes/<name>.cfg` for the include list or `cook/dishes/<name>.cfg` for the flattened kickstart.
|
|
|
|
- **The `%packages` sections are merged and sorted by pykickstart** — that is expected canonical output.
|
|
|
|
## Acknowledgement
|
|
|
|
Thanks to the main contributors of the official Fedora kickstart files repository, and related tools:
|
|
|
|
> Adam Miller, Bastien Nocera, Bruno Wolff III, Bryan Kearney, Chitlesh Goorah, Christoph Wickert, Colin Walters, Fabian Affolter, Igor Pires Soares, Jens Petersen, Jeremy Katz, Jeroen van Meeuwen Jesse Keating, Luya Tshimbalanga, Matthias Clasen, Pedro Silva, Rahul Sundaram, Sebastian Dziallas Sebastian Vahl, wart. More information here : https://pagure.io/fedora-kickstarts |