roots/phyllomeos
1
0
Fork 0
mirror of https://github.com/PhyllomeOS/phyllomeos.git synced 2024-10-02 14:25:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

improved README

Browse Source
This commit is contained in:
lukas 2021-11-14 18:49:01 +01:00
parent a91db8456e
commit e5bcd414f0
1 changed files with 56 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
README.md
View File

@ -2,71 +2,80 @@
> Virtualization for the rest of us
## What
*Phyllome OS is a [Fedora Remix](https://fedoraproject.org/wiki/Remix) based on [Fedora Server 35](https://getfedora.org/en/server/) designed to leverage hardware-assisted virtualization and VirtIO-based paravirtualization to make it easier to run modern UEFI-compatible guest operating systems locally.*
This repository contains the basic building blocks required for deploying [Phyllome OS](https://phyllo.me/) bare-metal or in a virtual machine, using kickstart files.
> This is the **alpha version** of Phyllome OS. Expect bugs and disappointment.
> Note: This is the **alpha version** of Phyllome OS. Expect bugs and disappointment
> External contributions for Phyllome OS are welcome. Have a look [here](https://kanboard.phyllo.me/b/CH7qd98J2v7egmodk/development) for some ideas on what to do next, or feel free to create an issue and suggest an idea you wish to work on.
> Note: External contributions for Phyllome OS are welcome. Have a look [here](https://kanboard.phyllo.me/b/CH7qd98J2v7egmodk/development) for some ideas on what to do next. To get the bigger picture, you could skim through the white paper.
> The Phyllome OS Project is **looking** for **core contributors**, willing to contribute regularly on the project. If you are interested about making cutting-edge open-source virtualization more accessible, please send an email to contact@phyllo.me.
> Note: The Phyllome OS Project is looking for **core contributors**, able to spend some a few hours on the project each week. If you are interested about making cutting-edge open-source virtualization more accessible, please send an email to contact@phyllo.me.
## What
This repository contains the basic building blocks required for deploying [Phyllome OS](https://phyllo.me/) in a virtual machine, using kickstart files.
Kickstart files are used to automate the installation and configuration of RPM-based operating systems.
> If you would like to install Phyllome OS on your computer, please follow [this guide](https://wiki.phyllo.me/deploy/install) instead.
### Structure of the repository
* `leaves` : this directory contains the basic buildings blocks for assembling Phyllome OS versions
* For instance, the Phyllome OS Desktop version optimized for Intel(tm) CPUs and Intel(tm) graphic cards, refered internally as `dhi`, can be found there (*d* for desktop; *h* for hypervisor; *i* for intel)
* Eventually, there will be three generic editions : **server**; **desktop** and **live**, with their own platform-dependant optimizations
* `flat` : this directory contains the end products in the form of stand-alone and ready-to-use kickstart files
* `post` : this directory contains scripts that are meant to be run after a successful installation
* `blocks` : this directory contains the basic building blocks for assembling Phyllome OS Desktop and Phyllome OS Server.
* This is where most of the development happens.
* `blocks-live` : this directory contains the basic building blocks for creating a live medium for Phyllome OS.
* The code in this directory usually lags behind what is found in the `blocks` directory.
* Ideally, the `blocks` and `blocks-live` repository would be merged, and the number of blocks reduced, to avoid code duplication.
* `leaves` : this directory contains the end product in the form of stand-alone and ready-to-use kickstart files.
* For instance, the Phyllome OS Desktop version optimized for Intel(tm) CPUs and Intel(tm) graphics cards, refered internally as `flat-dhi`, is stored there (*d* stands for desktop, *h* for hypervisor and *i* for intel).
* `post` : this directory contains scripts that are meant to be run after a successful installation, after Phyllome OS has started
* Ideally, these code snippets will be merged with existing building blocks, or summoned as a systemd unit.
## How to hack Phyllome OS
Hacking kickstart files is the main way to assemble and configure Phyllome OS, which is RPM-based. Kickstart files are snippets of code which automate the installation of RPM-based Linux distributions.
> Only Linux-based development is possible at the moment, sorry. Support for macOS and Windows-based development will follow.
> Note : The steps to deploy Phyllome OS bare-metal are available on the [external wiki]().
As of now, hacking kickstart files is the main way to develop Phyllome OS.
Have a look [here](https://docs.fedoraproject.org/en-US/fedora/rawhide/install-guide/appendixes/Kickstart_Syntax_Reference/) to learn the kickstart syntax.
### Requirements
* A x86_64 platform with hardware-assisted virtualization enabled
* A recent Linux Kernel (> 5.X)
* The `virt-install` and `virt-manager` tools
* `libvirt` and `qemu-kvm` up and running
* Nested-virtualization enabled
* A Linux distribution, with a recent Linux Kernel (> 5.X)
* A x86_64 platform with hardware-assisted virtualization [enabled](https://wiki.phyllo.me/deploy/prepare)
* Nested-virtualization enabled
* `virt-install` and `virt-manager`, as well as `libvirt` and `qemu-kvm` up and running
### The prerequisites
**AMD-based systems only**, enable nested-virtualization, then reboot:
**Enable** nested-virtualization on **AMD-based systems**, then reboot:
```
sudo echo "options kvm_amd nested=1" >> /etc/modprobe.d/kvm.conf
```
**Intel-based systems only**, enable nested-virtualization, then reboot:
**Enable** nested-virtualization on **Intel-based systems**, then reboot:
```
sudo echo "options kvm_intel nested=1" >> /etc/modprobe.d/kvm.conf`
```
Install the prerequisites on Fedora 34
**Install the prerequisites on Fedora 35**
```
sudo dnf install -y qemu-kvm libvirt libvirt-daemon-config-network libvirt-daemon-kvm virt-install virt-top virt-manager libguestfs-tools python3-libguestfs guestfs-tools
sudo dnf install -y qemu-kvm libvirt libvirt-daemon-config-network libvirt-daemon-kvm virt-install virt-top virt-manager libguestfs-tools python3-libguestfs guestfs-tools pykickstart
```
Install the prerequisites on Ubuntu 20.4 or Debian 11
**Install the prerequisites on Ubuntu 20.4 or Debian 11**
```To be done```
### Hack
### Hack around
From within your favorite terminal:
Clone this repository:
```
git clone https://github.com/PhyllomeOS/PhyllomeOS.git
```
Hack files inside the `leaves` directory.
Modify some files, typically inside the `blocks` directory.
When you are done, move to the `flat` directory:
@ -74,23 +83,24 @@ When you are done, move to the `flat` directory:
cd ./PhyllomeOS/flat/
```
Then, merge the kickstart leaves into a single file, a process known as flattening. Here, we take the Phyllome OS Desktop edition optimized for Intel(tm) CPUs and Intel(tm) graphic cards, also known as `dhi`, as an example :
Then, merge the kickstart basic building blocks into a single file, a process called flattening.
```
ksflatten -c ../leaves/dhi.cfg -o flat-dhi.cfg
ksflatten -c ../blocks/dhi.cfg -o flat-dhi.cfg
```
If any error is detected, go back and fix them.
## Fire it up!
### Fire it up!
For testing and development purposes, Phyllome OS can be deployed inside a virtual machine, as a guest hypervisor.
For testing purposes, Phyllome OS can be deployed inside a virtual machine, as a guest hypervisor.
> Note: it may eventually switch to container-based development.
The following command will automatically deploy the alpha version of Phyllome OS, tuned for Intel CPUs and Intel graphics cards.
> Note: the following script relies on a network-accessible kickstart file tuned for Intel CPUs and GPUs.
It uses a Q35 virtual motherboard, a UEFI-based firmware, virtio-devices accross the board, 2 vCPUs, 4 GB of RAM and a disk of 5 GB.
This script will automatically deploy the alpha version of Phyllome OS, on a Q35 virtual motherboard, a UEFI-based firmware, virtio-devices accross the board, 2 vCPUs, 4 GB of RAM and a disk of 5 GB.
> Adjust it according to your need.
Adjust it according to your need. When ready, copy and paste it to your terminal and fire it up!
When ready, copy and paste it to your terminal.
```
virt-install \
@ -118,7 +128,7 @@ virt-install \
--location=https://download.fedoraproject.org/pub/fedora/linux/releases/35/Everything/x86_64/os/ \
--initrd-inject flat-dhi.cfg --extra-args "inst.ks=file:flat-dhi.cfg"
```
You should see the following message.
```
Starting install...
Retrieving file vmlinuz... | 10 MB 00:00
@ -132,7 +142,7 @@ Allocating 'flat-dhi.img' | 5.0 GB 00:00
Domain is still running. Installation may be in progress.
You can reconnect to the console to complete the installation process.
```
The process will be launched behind the scene. You can open `virt-manager` and connect to the virtual machine to follow the process. Eventually, you will be greated with this screen:
The installation process will be launched behind the scene. You can open `virt-manager` and connect to the virtual machine console to follow the process. Eventually, you will be greeted with this screen:
![greetings](./img/greetings.png)
@ -140,30 +150,27 @@ After you are done setting your user account, `virt-manager` will automatically
![greetings](./img/desktop.png)
If the installation is a success and your feature is working as intended, you are welcome to create a pull request. Thank you!
## Phyllome OS
Phyllome OS is a [Fedora Remix](https://fedoraproject.org/wiki/Remix) based on [Fedora Server 35](https://getfedora.org/en/server/) designed to leverage hardware-assisted virtualization and VirtIO-based paravirtualization to run modern UEFI-compatible guest operating systems locally.
The goal is to maximize ease-of-use and compatibility. As such, Phyllome OS intends to become the easiest way to virtualize modern operating systems, by integrating pertinent open-source software such as `libvirt`, `qemu-kvm` (and then the `Cloud Hypervisor`) and `virt-manager`.
Phyllome OS goal is to maximize ease-of-use and compatibility. As such, it intends to become the easiest way to virtualize modern operating systems locally, by integrating pertinent open-source software such as `libvirt`, `qemu-kvm` (and eventually `Cloud Hypervisor`), as well as `virt-manager`.
A user should not have to manage Phyllome OS: it should be able to pick its favorite operating system and Phyllome OS should run it, no question asked.
Do you want to know more about Phyllome OS design and context ? If so, please have a look at [the white paper]().
> Note : at the exception of open-source [Darwin derivatives](https://en.wikipedia.org/wiki/Darwin_(operating_system)#Derived_projects), Phyllome OS **won't** offer support running macOS on non-Apple hardware.
> Note : at the exception of open-source [Darwin derivatives](https://en.wikipedia.org/wiki/Darwin_(operating_system)#Derived_projects), Phyllome OS **strongly** discourage users from running proprietary, darwin-based derivatives on non-Apple hardware.
### The Phyllome OS Project
The Phyllome OS Project relies on multiple tools, including the following front-facing tools:
The Phyllome OS Project relies on multiple tools, including the following public-facing tools:
* **The wiki**: Have a look at the [wiki repository](https://github.com/PhyllomeOS/wiki) for more information on how you can contribute to improve the documentation.
* **Issues tracker**: public, read-only issue tracking is [available online](https://kanboard.phyllo.me/b/CH7qd98J2v7egmodk/development)
* **The website**: the website repository is [available here](https://github.com/PhyllomeOS/www)
* **Code repository**: GitHub is being used to host the code, with a mirror pointing to https://git.phyllo.me
* **Wiki**: Have a look at the [wiki repository](https://github.com/PhyllomeOS/wiki) for more information on how you can contribute to improve the documentation.
* **Issues tracker**: a public, read-only issue tracking is [available online](https://kanboard.phyllo.me/b/CH7qd98J2v7egmodk/development). For now one, GitHub issue tracking will be used to track development only issues.
* **Code repository**: GitHub is used to host the code, with a mirror pointing to git.phyllo.me
## Licence
* [GENERAL PUBLIC LICENCE 3](./LICENSE.md)
* [MIT](./LICENSE.md) for the most part, with some [GPL](./blocks-live/LICENSE.md) code.
## Acknowledgement