diff --git a/README.md b/README.md index 516ba328..4758796d 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,140 @@ -# Podman Desktop Bootable Container Extension +# BootC (Bootable Container) Extension for Podman Desktop -This extension provides support for bootable containers (bootc and image builder) -to Podman Desktop. +Want to convert your container to a bootable operating system? Download this extension! -# Features +Easily go from container to VM / ISO-on-a-USB / RAW image! -- Adds a badge to all bootable containers (currently looks for the - 'ostree.bootable' label, but this will change). -- Adds a custom icon to all bootable containers. -- Adds a menu item to bootable containers to launch image builder to create - a disk image. +## Technology -# How to test/develop +The **Bootable Container (bootc)** extension utilizes [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) in order to create bootable OS images. -To run in development mode, clone Podman Desktop and this repo. Follow the -Podman Desktop instructions on launching in dev mode, but add the path to -this extension: +Within [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) the tool uses [bootc](https://containers.github.io/bootc/) as a basis for conversion to achieve the bootable OS as well as libraries such as [libostree](https://ostreedev.github.io/ostree/) and [ostree-rs-ext](https://github.com/ostreedev/ostree-rs-ext). -`yarn watch --extension-folder ~/git/containers/podman-desktop-extension-bootc` +## Extension Features + +* Create bootable container images +* One-click launching of VM's +* Built-in Podman Desktop UI additions to help differentiate bootc to normal containers (bootc badges in images) +* Custom icon to help indicate bootc containers + +## Use Case + +Go from a a [bootc](https://containers.github.io/bootc/) compatible Containerfile: + +```Containerfile +FROM quay.io/centos-bootc/fedora-bootc:eln + +# Install an HTTP server +RUN dnf -y install httpd; dnf -y clean all +``` + +To a bootable OS image format: + +* `qcow2`: QEMU Disk Images +* `ami`: Amazon Machine Images +* `raw`: RAW disk image an MBR or GPT partition table +* `iso`: Unattended installation method (USB Sticks / Install-on-boot) + +## Requirements before Installation + +Disclaimer: This is **EXPERIMENTAL** and all features are subject to change as we develop the extension. + +### Requirement 1. Be on macOS M1/M2/M3 (silicon) + +As of right now, this is being tested and only works on macOS silicon architecture. + +Use Windows / Linux / Mac (Intel-based) at your own risk. + +Windows & Linux support will be implemented in the future. + +### Requirement 2. Rootful mode on Podman Machine + +Make sure your `podman machine` has rootful mode enabled. + +This can be done through the CLI to an already deployed VM: + +```sh +podman machine stop +podman machine set --rootful +podman machine start +``` + +Or set when initially creating a Podman Machine via Podman Desktop: + +![rootful setup](https://private-user-images.githubusercontent.com/6422176/297535513-2f4e1838-fc93-4f54-b9d3-297920bfc32f.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MDU1MzA1MDAsIm5iZiI6MTcwNTUzMDIwMCwicGF0aCI6Ii82NDIyMTc2LzI5NzUzNTUxMy0yZjRlMTgzOC1mYzkzLTRmNTQtYjlkMy0yOTc5MjBiZmMzMmYucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI0MDExNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNDAxMTdUMjIyMzIwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9Njk0OTc2ZTdiZWY1NTA5Mjc0ZDFjMGRlYTQxNGYyNWFhNWM0MWE5MjBjZTdiN2U2OWJlOWE2Y2Y1MGM5YTNkMiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmYWN0b3JfaWQ9MCZrZXlfaWQ9MCZyZXBvX2lkPTAifQ.WipmMc_S9grSp9ja_HFRLheqwgZHM1dc4LP5z8EcFRQ) + +### Requirement 3. Vfkit installed for automatic VM preview + +> NOTE: MacOS only. Only applicable if you would like to view the VM with one-click. Otherwise, use the raw / qcow2 / iso. + +[Vfkit](https://github.com/crc-org/vfkit) is a CLI interface to create virtual machines using Apple's virtualization framework. + +This can be [installed via brew](https://github.com/crc-org/vfkit?tab=readme-ov-file#installation): + +```sh +brew tap cfergeau/crc +brew install vfkit +``` + +## Installation + +Each new commit to `main` will produce a new release to [ghcr.io/containers/podman-desktop-extension-bootc](https://ghcr.io/containers/podman-desktop-extension-bootc). + +Use the `ghcr.io/containers/podman-desktop-extension-bootc` image. + +This can be installed through the **Extensions** page of Podman Desktop: + + + + +## Usage + +1. **Build your bootc-enabled Containerfile:** + +> In our example, we are going to change the root password for testing purposes when accessing the OS. + +```Containerfile +FROM quay.io/centos-bootc/fedora-bootc:eln + +# Change the root password +RUN echo "root:supersecret" | chpasswd +``` + + + +2. **Push the image:** + +> IMPORTANT NOTE: This must be a **PUBLICALLY** accessible registry, this will be fixed in the future to use a local container storage + + + +3. **Build the image:** + +> Build the disk image, this takes approximatley 2-5 minutes depending on the performance of your machine. + + + +4. **View the logs:** + +> You can now view the conversion process within the Containers section + + + +5. **Launch the VM (experimental):** + +> You can press the "Launch VM" button to test the virtual machine. + + + +# Development & Contribution + +Want to help develop and contribute to the bootc extension? + +You can use `yarn watch --extension-folder` from the Podman Desktop directory to automatically rebuild and test the bootc extension: + +```sh +git clone https://github.com/containers/podman-desktop +git clone https://github.com/containers/podman-desktop-extension-bootc +cd podman-desktop +yarn watch --extension-folder ../podman-desktop-extension-bootc +``` \ No newline at end of file