phyllomeos/README.md

Kickstart Phyllome OS

Phyllome OS uses the kickstart installation method 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.

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, 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:

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