roots/phyllomeos
1
0
Fork 0
mirror of https://github.com/PhyllomeOS/phyllomeos.git synced 2024-12-22 13:05:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

improve the README

Browse Source 
Switch to qemu session for the example.
Target Phyllome OS Desktop instead of a specialized edition
This commit is contained in:
lukas 2021-11-27 15:40:35 +01:00
parent 8eda17ef1a
commit 761d2cab6b
1 changed files with 70 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
README.md
View File

@ -1,22 +1,22 @@
# Phyllome OS # Phyllome OS
> Virtualization for the rest of us > *Virtualization for the rest of us*
*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 paravirtualization to make it easier to run modern guest operating systems locally.* This is the **alpha version** of Phyllome OS. Expect bugs and disappointment.
> This is the **alpha version** of Phyllome OS. Expect bugs and disappointment.
> External contributions to 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. Also, it might be good to skim through the [white-paper](https://files.phyllo.me/s/oYwfxYpZcbppwr6) to understand what it is about and what the project is trying to achieve. > External contributions to 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. Also, it might be good to skim through the [white-paper](https://files.phyllo.me/s/oYwfxYpZcbppwr6) to understand what it is about and what the project is trying to achieve.
> The Phyllome OS Project is **looking for core contributors**, willing to contribute regularly to the project. If you are interested in making cutting-edge open-source virtualization more accessible, please send an email to contact@phyllo.me. > The Phyllome OS Project is **looking for core contributors**, willing to contribute regularly to the project. If you are interested in making cutting-edge open-source virtualization more accessible, email to contact@phyllo.me.
*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 paravirtualization to make it easier to run modern guest operating systems locally.*
## What ## What
This repository contains the basic building blocks required to deploy [Phyllome OS](https://phyllo.me/) in a virtual machine, using kickstart files. This repository contains the basic building blocks required to deploy the plaform-agnostic edition of [Phyllome OS](https://wiki.phyllo.me/deploy/rightforyou#phyllome-os-versions) Desktop, inside a virtual machine, using a kickstart file.
Kickstart files are used to automate the installation and configuration of RPM-based operating systems. 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. > If you would like to install Phyllome OS on your computer instead, as a replacement of your current operating system, please follow [this guide](https://wiki.phyllo.me/deploy/prepare) instead.
### Structure of the repository ### Structure of the repository
@ -24,49 +24,76 @@ Kickstart files are used to automate the installation and configuration of RPM-b
* This is where most of the development happens. * 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. * `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. * The code in this directory usually lags behind what is found in the `blocks` directory.
* The `blocks` and `blocks-live` repository will eventually be merged, and the number of blocks will be reduced to avoid code duplication. * Ideally, the `blocks` and `blocks-live` directory will eventually be merged, and the number of blocks will be reduced to avoid code duplication.
* `leaves` : this directory contains the end product in the form of stand-alone and ready-to-use kickstart files. * `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, referred to internally as `flat-dhi`, is stored there (*d* stands for desktop, *h* for hypervisor and *i* for intel). * For instance, the kickstart file to deploy the Phyllome OS Desktop edition optimized for Intel(tm) CPUs and GPUs, referred to as Phyllome Desktop II.
* `post` : this directory contains scripts that are meant to be run after a successful installation, after Phyllome OS has started. * `post` : this directory contains scripts that are meant to be run manually by the user after a successful installation.
* Ideally, these code snippets will be merged with existing building blocks, or summoned as a systemd unit. * These code snippets will eventually be included inside existing building blocks, summoned as a systemd unit after a successful installation, or turned into RPM-packages.
## How to hack Phyllome OS ## How to hack Phyllome OS
> Only Linux-based development is possible at the moment, sorry. Support for macOS and Windows-based development will follow. > Only Linux-based development is possible at the moment. Support for macOS and Windows-based development will follow.
As of now, hacking kickstart files is the main way to develop Phyllome OS. 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. Have a look [here](https://docs.fedoraproject.org/en-US/fedora/rawhide/install-guide/appendixes/Kickstart_Syntax_Reference/) to learn the kickstart syntax. You can also study the official kickstart for all Fedora versions [here](https://pagure.io/fedora-kickstarts/tree/main).
### Requirements ### Requirements
* A Linux distribution, with a recent Linux Kernel (> 5.X) * 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) * An x86_64 platform with hardware-assisted virtualization [enabled](https://wiki.phyllo.me/deploy/prepare)
* Nested-virtualization enabled * Nested-virtualization enabled (optional but better to have)
* `virt-install` and `virt-manager`, as well as `libvirt` and `qemu-kvm` up and running * `virt-install` and `virt-manager`, as well as `libvirt` and `qemu-kvm` up and running
**Enable** nested-virtualization on **AMD-based systems**, then reboot: #### Enable nested-virtualization
* **Enable** nested-virtualization on **AMD-based systems**, then reboot:
``` ```
sudo echo "options kvm_amd nested=1" >> /etc/modprobe.d/kvm.conf sudo echo "options kvm_amd nested=1" >> /etc/modprobe.d/kvm.conf
``` ```
* Verify that nested-virtualization is activated, using the following command, which should return a `1`:
```
cat /sys/module/kvm_amd/parameters/nested
1
```
**Enable** nested-virtualization on **Intel-based systems**, then reboot: **Enable** nested-virtualization on **Intel-based systems**, then reboot:
``` ```
sudo echo "options kvm_intel nested=1" >> /etc/modprobe.d/kvm.conf` sudo echo "options kvm_intel nested=1" >> /etc/modprobe.d/kvm.conf`
``` ```
**Install the prerequisites on Fedora 35** * Verify that nested-virtualization is activated, using the following command, which should return a `1`:
```
cat /sys/module/kvm_intel/parameters/nested
1
```
#### 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 pykickstart 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``` ```To be done```
#### Define new URI for the virtual machine manager
> GNOME Shell only
By default, `virt-manager` connect to `libvirtd` as *root*. The following command will add a new URI to `virt-manager` so that you can manage virtual machines using your potentially unprivileged account.
```
gsettings set org.virt-manager.virt-manager.connections uris "['qemu:///system', 'qemu:///session']"
gsettings set org.virt-manager.virt-manager.connections autoconnect "['qemu:///system', 'qemu:///session']"
```
### Hack around ### Hack around
Clone this repository: Clone this repository:
@ -75,59 +102,59 @@ Clone this repository:
git clone https://github.com/PhyllomeOS/PhyllomeOS.git git clone https://github.com/PhyllomeOS/PhyllomeOS.git
``` ```
Modify some files, typically inside the `blocks` directory. Modify some files, typically inside the `blocks` directory, using your favorite editor.
When you are done, move to the `flat` directory:
```
cd ./PhyllomeOS/flat/
```
Then, merge the kickstart basic building blocks into a single file, a process called 'flattening'. Then, merge the kickstart basic building blocks into a single file, a process called 'flattening'.
``` ```
ksflatten -c ../blocks/dhi.cfg -o flat-dhi.cfg ksflatten -c virtual-desktop-hypervisor.cfg -o ../leaves/virtual-phyllome-desktop.cfg
```
> If any errors are detected, go back and fix them.
When you are done, move to the `leaves` directory:
```
cd ../leaves
``` ```
If any errors are detected, go back and fix them.
### Fire it up! ### Fire it up!
For testing purposes, Phyllome OS can be deployed inside a virtual machine, as a guest hypervisor. The following command will read your flattened file and use it to automatically bootstrap your modified revision of Phyllome OS on a virtual machine with 2 vCPUs, 4 GB of RAM and a disk of 5 GB.
The following command will automatically deploy the alpha version of Phyllome OS, tuned for Intel CPUs and Intel graphics cards.
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.
> Adjust it according to your needs. > Adjust it according to your needs.
When ready, copy and paste it to your terminal.
``` ```
virt-install \ virt-install \
--connect qemu:///system \ --connect qemu:///session \
--metadata description="Phyllome OS Desktop, generic edition" \
--os-variant detect=off \
--virt-type kvm \ --virt-type kvm \
--arch x86_64 \ --arch x86_64 \
--machine q35 \ --machine q35 \
--name phyllome-alpha \ --name virtual-phyllome-desktop \
--boot uefi \ --boot uefi \
--cpu host-model,topology.sockets=1,topology.cores=2,topology.threads=1 \ --cpu host-model,topology.sockets=1,topology.cores=2,topology.threads=1 \
--vcpus 2 \ --vcpus 2 \
--memory 4096 \ --memory 4096 \
--video virtio \ --video virtio \
--graphics spice,listen=none \
--channel spicevmc \ --channel spicevmc \
--autoconsole none \ --autoconsole none \
--console pty,target.type=virtio \
--sound none \ --sound none \
--network type=user,model=virtio \
--controller type=virtio-serial \ --controller type=virtio-serial \
--controller type=usb,model=none \ --controller type=usb,model=none \
--controller type=scsi,model=virtio-scsi \ --controller type=scsi,model=virtio-scsi \
--network network=default,model=virtio \
--input type=keyboard,bus=virtio \ --input type=keyboard,bus=virtio \
--input type=tablet,bus=virtio \ --input type=tablet,bus=virtio \
--rng /dev/urandom,model=virtio \ --rng /dev/urandom,model=virtio \
--disk path=/var/lib/libvirt/images/flat-dhi.img,format=raw,bus=virtio,cache=writeback,size=5 \ --disk path=~/.local/share/libvirt/images/virtual-phyllome-desktop.img,format=raw,bus=virtio,cache=writeback,size=5 \
--location=https://download.fedoraproject.org/pub/fedora/linux/releases/35/Everything/x86_64/os/ \ --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" --initrd-inject virtual-phyllome-desktop.cfg --extra-args "inst.ks=file:virtual-phyllome-desktop.cfg"
``` ```
You should see the following message: You should see the following message:
``` ```
Starting install... Starting install...
@ -137,7 +164,7 @@ Allocating 'virtinst-inlu7cmw-vmlinuz' | 10 MB 00:00
Transferring virtinst-inlu7cmw-vmlinuz | 10 MB 00:00 Transferring virtinst-inlu7cmw-vmlinuz | 10 MB 00:00
Allocating 'virtinst-2dd8ghse-initrd.img' | 79 MB 00:00 Allocating 'virtinst-2dd8ghse-initrd.img' | 79 MB 00:00
Transferring virtinst-2dd8ghse-initrd.img | 79 MB 00:01 Transferring virtinst-2dd8ghse-initrd.img | 79 MB 00:01
Allocating 'flat-dhi.img' | 5.0 GB 00:00 Allocating 'virtual-phyllome-desktop.img' | 5.0 GB 00:00
Domain is still running. Installation may be in progress. Domain is still running. Installation may be in progress.
You can reconnect to the console to complete the installation process. You can reconnect to the console to complete the installation process.
@ -158,7 +185,7 @@ Phyllome OS goal is to maximize ease-of-use and compatibility. As such, it inten
Users should not have to manage Phyllome OS: they should be able to pick their favorite operating system and Phyllome OS should run it, no questions asked. Users should not have to manage Phyllome OS: they should be able to pick their favorite operating system and Phyllome OS should run it, no questions asked.
> Note : with the exception of open-source [Darwin derivatives](https://en.wikipedia.org/wiki/Darwin_(operating_system)#Derived_projects), Phyllome OS **strongly** discourages users from running proprietary, darwin-based derivatives on non-Apple hardware. > Note : expect for open-source [Darwin derivatives](https://en.wikipedia.org/wiki/Darwin_(operating_system)#Derived_projects), Phyllome OS **strongly** discourages users from running proprietary, darwin-based derivatives on non-Apple hardware.
### The Phyllome OS Project ### The Phyllome OS Project
@ -170,7 +197,7 @@ The Phyllome OS Project relies on multiple tools, including the following public
## License ## License
* [MIT](./LICENSE.md) for the most part, with some [GPL](./blocks-live/LICENSE.md) code. * [MIT](./LICENSE.md) for the most part, alongside [GPL](./blocks-live/LICENSE.md) licensed code.
## Acknowledgement ## Acknowledgement