phyllomeos/README.md

# 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, e.g. `desktop_44_standard_grub_gnome_guest-agents`, when prompted:

```
./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.
After a successfull installation, the virtual machine will shutdown and be ready to use when powered on again.

## 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 [--as qcow2] [--root-size MiB] [--extra-ks FILE]
```

It picks a dish the same way `deploy.sh` does and writes the result under
`./build/`. 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/desktop_44_standard_grub_gnome.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 edition (a group named e.g. `server`) in `cook/recipes_manifest.yaml` with the desired variants; the cartesian product of its list values generates one dish per combination.

### Useful targets (in `cook/`)

```
make all         # generate recipes + dishes, lint, and validate (default)
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