diff --git a/README.md b/README.md index af441d1b..81d8e811 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,56 @@ in alignment with the project. - Be a backend for - Work on both MacOS and Linux +## Running + +First and foremost, `podman-bootc` requires a *rootful* Podman Machine to be +running, which is the default on MacOS and Windows. On Linux, make sure to +create a Podman Machine via `podman machine init --rootful --now` which implies +that you need to run podman with `--remote` command to make built images +available to `podman-bootc`. + +The core command right now is: + +```shell +podman-bootc run +``` + +This command creates a new virtual machine, backed by a persistent disk +image from a "self install" of the container image, and makes a SSH +connection to it. + +This requires SSH to be enabled by default in your base image; by +default an automatically generated SSH key is injected via a systemd +credential attached to qemu. + +Even after you close the SSH connection, the machine continues to run. + +### Other commands: + +- `podman-bootc list`: List running VMs +- `podman-bootc ssh`: Connect to a VM +- `podman-bootc rm`: Remove a VM + +### Architecture + +At the current time the `run` command uses a +[bootc install](https://containers.github.io/bootc/bootc-install.html) +flow - where the container installs itself executed in a privileged +mode inside the podman-machine VM. + +The installation target is a raw disk image is created on the host, but loopback +mounted over virtiofs/9p from the podman-machine VM. + +(The need for a real-root privileged container to write Linux filesystems is part of the + rationale for requiring podman-machine even on Linux is that + it keeps the architecture aligned with MacOS (where it's always required)) + +In the future, support for installing via [Anaconda](https://github.com/rhinstaller/anaconda/) +and [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) +will be added. + +## Installation + ### MacOS First be sure you have the Podman Desktop [bootc extension requirements](https://github.com/containers/podman-desktop-extension-bootc?tab=readme-ov-file#requirements). @@ -35,11 +85,7 @@ or by other mean and make it available in the path. ### Fedora -You first must have `podman-machine` installed. -It is required to have a *rootful* podman machine setup -via e.g. `podman machine init --rootful --now`. - -For Fedora 40 and Rawhide we provide a COPR repository. +For Fedora 40+ and Rawhide we provide a COPR repository. First, enable the COPR repository: ``` @@ -67,46 +113,3 @@ To compile it, just run in the project directory: ```shell make ``` - - -## Running - -The core command right now is: - -```shell -podman-bootc run -``` - -This command creates a new virtual machine, backed by a persistent disk -image from a "self install" of the container image, and makes a SSH -connection to it. - -This requires SSH to be enabled by default in your base image; by -default an automatically generated SSH key is injected via a systemd -credential attached to qemu. - -Even after you close the SSH connection, the machine continues to run. - -### Other commands: - -- `podman-bootc list`: List running VMs -- `podman-bootc ssh`: Connect to a VM -- `podman-bootc rm`: Remove a VM - -### Architecture - -At the current time the `run` command uses a -[bootc install](https://containers.github.io/bootc/bootc-install.html) -flow - where the container installs itself executed in a privileged -mode inside the podman-machine VM. - -The installation target is a raw disk image is created on the host, but loopback -mounted over virtiofs/9p from the podman-machine VM. - -(The need for a real-root privileged container to write Linux filesystems is part of the - rationale for requiring podman-machine even on Linux is that - it keeps the architecture aligned with MacOS (where it's always required)) - -In the future, support for installing via [Anaconda](https://github.com/rhinstaller/anaconda/) -and [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) -will be added.