Revamp docs

Add a quick start to the README, reorganize and make the main
documentation less reference-like, and add a man page.

Signed-off-by: Alberto Faria <[email protected]>

.gitignore

@@ -1,3 +1,2 @@
+/out
 /target
-/bin/
-/targets/

Makefile

@@ -7,30 +7,35 @@ CARGO      ?= cargo
 SELINUXOPT ?= $(shell test -x /usr/sbin/selinuxenabled && selinuxenabled && echo -Z)
 
 binpath := $(DESTDIR)/$(PREFIX)/bin/crun-vm
+manpath := $(DESTDIR)/$(PREFIX)/share/man/man1/crun-vm.1.gz
 
-.PHONY: build
-build:
+all: out/crun-vm out/crun-vm.1.gz
+
+.PHONY: out/crun-vm
+out/crun-vm:
+	mkdir -p $(@D)
 	$(CARGO) build --release
-	mkdir -p bin
-	cp target/release/crun-vm bin/crun-vm
+	cp target/release/crun-vm $@
 
-.PHONY: build-debug
-build-debug:
-	$(CARGO) build
-	mkdir -p bin
-	cp target/debug/crun-vm bin/crun-vm.debug
+out/crun-vm.1.gz: docs/5-crun-vm.1.ronn
+	mkdir -p $(@D)
+	ronn --pipe --roff $< | gzip > $@
 
 .PHONY: clean
 clean:
-	rm -fr bin target
+	rm -fr out target
 
 .PHONY: install
-install: build
-	install ${SELINUXOPT} -D -m 0755 bin/crun-vm $(binpath)
+install: out/crun-vm install-man
+	install ${SELINUXOPT} -D -m 0755 $< $(binpath)
+
+.PHONY: install-man
+install-man: out/crun-vm.1.gz
+	install ${SELINUXOPT} -D -m 0644 $< $(manpath)
 
 .PHONY: uninstall
 uninstall:
-	rm -f $(binpath)
+	rm -f $(binpath) $(manpath)
 
 .PHONY: lint
 lint:

README.md

@@ -1,46 +1,107 @@
 # The crun-vm OCI Runtime
 
 **crun-vm** is an [OCI Runtime] that enables [Podman], [Docker], and
-[Kubernetes] to run QEMU-compatible Virtual Machine (VM) images.
+[Kubernetes] to run QEMU-compatible Virtual Machine (VM) images. This means you
+can:
 
-- Run **VMs** as easily as you run **containers**.
-- Manage containers and VMs **together** using the **same** standard tooling.
-- **No need** for in-depth knowledge on virtualization technologies like libvirt
-  or KubeVirt.
+  - Run **VMs** as easily as you run **containers**.
+  - Manage containers and VMs **together** using the **same** standard tooling.
+
+---
 
 <p align="center">
   <img src="docs/example.gif" width="680" />
 </p>
 
+---
+
+<table>
+<tr>
+<td width="450" valign="top">
+
+### Quick start
+
+Install crun-vm:
+
+```console
+$ dnf install crun-vm
+```
+
+Launch a VM from a disk image packaged in a container:
+
+```console
+$ podman run --runtime crun-vm -it \
+    quay.io/containerdisks/fedora:40
+```
+
+Launch a VM from a disk image under `my-image-dir/`:
+
+```console
+$ podman run --runtime crun-vm -it \
+    --rootfs my-image-dir/
+```
+
+Launch a VM from a [bootable container]:
+
+```console
+$ podman run --runtime crun-vm -it \
+    quay.io/fedora/fedora-bootc:40
+```
+
+Set the password for a VM's default user:
+
+```console
+$ podman run --runtime crun-vm -it \
+    quay.io/containerdisks/fedora:40 \
+    --password pass  # for user "fedora"
+```
+
+Exec (ssh) into a VM:
+
+```console
+$ podman exec -it --latest -- --as fedora
+```
+
+<p></p>
+</td>
+<td valign="top">
+
 ### Major features
 
-  - Use it with **Podman**, **Docker**, or **Kubernetes**.
-  - Launch VMs from VM **image files** present on the host or packaged into
-    **container images**.
   - Control VM **CPU** and **memory** allocation.
-  - Provide **cloud-init** and **Ignition** configurations to VMs.
-  - **Mount directories** into VMs.
+  - Pass **cloud-init** or **Ignition** configs to VMs.
+  - Mount **directories** into VMs.
   - Pass **block devices** through to VMs.
-  - Expose **qcow2 files** and other **disk images** to VMs as block devices.
+  - Expose additional **disk images** to VMs.
   - **Forward ports** from the host to VMs.
-  - **`podman exec`**/**`docker exec`**/**`kubectl exec`** into VMs.
+  - **`podman|docker|kubectl exec`** into VMs.
+
+---
 
 ### Documentation
 
   1. [Installing crun-vm](docs/1-installing.md)
-  2. [Using crun-vm as a Podman or Docker runtime](docs/2-podman-docker.md)
-  3. [Using crun-vm as a Kubernetes runtime](docs/3-kubernetes.md)
+  2. [Running VMs with **Podman** or **Docker**](docs/2-podman-docker.md)
+  3. [Running VMs as **systemd** services](docs/3-systemd.md)
+  4. [Running VMs in **Kubernetes**](docs/4-kubernetes.md)
+  5. [**crun-vm(1)** man page](docs/5-crun-vm.1.ronn)
 
-> [!TIP]
-> See also how you can [combine **crun-vm** and **Podman Quadlet** to easily
-> manage both containers and VMs through **systemd**](/examples/quadlet).
+---
 
 ### License
 
 This project is released under the GPL 2.0 (or later) license. See
 [LICENSE](LICENSE).
 
+<p></p>
+</td>
+</tr>
+</table>
+
+[bootable container]: https://containers.github.io/bootable
 [Docker]: https://www.docker.com/
 [Kubernetes]: https://kubernetes.io/
-[Podman]: https://podman.io/
+[KubeVirt]: https://kubevirt.io/
 [OCI Runtime]: https://github.com/opencontainers/runtime-spec/blob/v1.1.0/spec.md
+[Podman]: https://podman.io/
+[systemd]: https://systemd.io/

docs/1-installing.md

@@ -1,96 +1,156 @@
 # 1. Installing crun-vm
 
-## On Fedora
+There are two steps to setting up crun-vm on a system:
 
-Run:
+  - Installing the actual `crun-vm` binary;
+  - Configuring Podman, Docker, and/or Kubernetes (whichever you intend to use
+    crun-vm with) to recognize crun-vm as a runtime.
+
+These steps are detailed in the sections below.
+
+<details open>
+  <summary><b>Navigation</b></summary>
+
+  1. **Installing crun-vm**
+     - [**Installing the `crun-vm` binary**](#installing-the-crun-vm-binary)
+       - [On Fedora](#on-fedora)
+       - [From source](#from-source)
+     - [**Making crun-vm available as a runtime**](#making-crun-vm-available-as-a-runtime)
+       - [To Podman](#to-podman)
+       - [To Docker](#to-docker)
+       - [To Kubernetes](#to-kubernetes)
+  2. [Running VMs with **Podman** or **Docker**](2-podman-docker.md)
+  3. [Running VMs as **systemd** services](3-systemd.md)
+  4. [Running VMs in **Kubernetes**](4-kubernetes.md)
+  5. [**crun-vm(1)** man page](5-crun-vm.1.ronn)
+
+</details>
+
+## Installing the `crun-vm` binary
+
+### On Fedora
 
 ```console
 $ dnf install crun-vm
 ```
 
-Podman will then be able to make use of the crun-vm runtime.
-
-To also set up crun-vm for use with Docker:
+### From source
+
+1. Install crun-vm's build dependencies:
+
+   - [cargo](https://doc.rust-lang.org/stable/cargo/getting-started/installation.html)
+   - [gzip](https://www.gzip.org/)
+   - [libselinux](https://github.com/SELinuxProject/selinux/tree/main/libselinux),
+     including development headers
+   - [ronn-ng](https://github.com/apjanke/ronn-ng)
+
+2. Install crun-vm's runtime dependencies:
+
+   - bash
+   - [coreutils](https://www.gnu.org/software/coreutils/)
+   - [crun](https://github.com/containers/crun)
+   - [crun-krun](https://github.com/containers/crun/blob/main/krun.1.md)
+   - [genisoimage](https://github.com/Distrotech/cdrkit)
+   - grep
+   - [libselinux](https://github.com/SELinuxProject/selinux/tree/main/libselinux)
+   - [libvirtd](https://gitlab.com/libvirt/libvirt) or
+     [virtqemud](https://gitlab.com/libvirt/libvirt)
+   - [passt](https://passt.top/)
+   - [qemu-img](https://gitlab.com/qemu-project/qemu)
+   - qemu-system-x86_64-core, qemu-system-aarch64-core, and/or other [QEMU
+     system emulators](https://gitlab.com/qemu-project/qemu) for the VM
+     architectures you want to support
+   - ssh
+   - [util-linux](https://github.com/util-linux/util-linux)
+   - [virsh](https://gitlab.com/libvirt/libvirt)
+   - [virtiofsd](https://gitlab.com/virtio-fs/virtiofsd)
+   - [virtlogd](https://gitlab.com/libvirt/libvirt)
+
+3. Install crun-vm's binary and man page:
 
-  - Merge the following configuration into `/etc/docker/daemon.json`:
+   ```console
+   $ make install
+   ```
 
-    ```json
-    {
-      "runtimes": {
-        "crun-vm": {
-          "path": "/usr/bin/crun-vm"
-        }
-      }
-    }
-    ```
+## Making crun-vm available as a runtime
 
-  - Reload the `docker` service for the new configuration to take effect:
+### To Podman
 
-    ```console
-    $ service docker reload
-    ```
+Nothing to do here, since Podman automatically recognizes crun-vm as a runtime.
+Commands like `podman create` and `podman run` can be made to use the crun-vm
+runtime by passing them the `--runtime crun-vm` option.
 
-## Build and install from source (on Fedora)
+<!--
+Paths search by Podman:
+  - `/usr/bin/crun-vm`
+  - `/usr/local/bin/crun-vm`
+  - `/usr/local/sbin/crun-vm`
+  - `/sbin/crun-vm`
+  - `/bin/crun-vm`
+  - `/run/current-system/sw/bin/crun-vm`
+ -->
 
-1. Install crun-vm's runtime dependencies:
+See [2. Using crun-vm and **Podman** or **Docker** to run a
+VM](2-podman-docker.md) to get started.
 
-   ```console
-   $ dnf install bash coreutils crun crun-krun genisoimage grep libselinux-devel libvirt-client libvirt-daemon-driver-qemu libvirt-daemon-log openssh-clients qemu-img qemu-system-x86-core sed shadow-utils util-linux virtiofsd
-   ```
+### To Docker
 
-2. Install Rust and Cargo if you do not already have Rust tooling available:
+1. Merge the following configuration into `/etc/docker/daemon.json` (creating
+   that directory and file if necessary):
 
-   ```console
-   $ dnf install cargo
+   ```json
+   {
+     "runtimes": {
+       "crun-vm": {
+         "path": "/usr/bin/crun-vm"
+       }
+     }
+   }
    ```
 
-3. Build crun-vm:
+2. Reload the `docker` service for the new configuration to take effect:
 
    ```console
-   $ cargo build
+   $ service docker reload
    ```
 
-4. Copy the `target/debug/crun-vm` binary to wherever you prefer:
+Commands like `docker create` and `docker run` can then be made to use the
+crun-vm runtime by passing them the `--runtime crun-vm` option.
 
-   ```console
-   $ cp target/debug/crun-vm /usr/local/bin/
-   ```
+See [2. Using crun-vm and **Podman** or **Docker** to run a
+VM](2-podman-docker.md) to get started.
 
-5. If you're using Podman:
+### To Kubernetes
 
-     - Merge the following configuration into
-       `/etc/containers/containers.conf`:
+For crun-vm to be usable as a runtime in a Kubernetes cluster, the latter must
+be use the [CRI-O] runtime. See the Kubernetes docs on [runtimes] for more
+information.
 
-       > For rootless Podman, you can instead use
-       > `${XDG_CONFIG_PATH}/containers/containers.conf`, where
-       > `$XDG_CONFIG_PATH` defaults to `${HOME}/.config`.
+1. Install crun-vm on all cluster nodes where pods may be scheduled, using any
+   of the methods [described above](#installing-the-crun-vm-binary).
 
-       ```toml
-       [engine.runtimes]
-       crun-vm = ["/usr/local/bin/crun-vm"]
-       ```
+2. Append the following to `/etc/crio/crio.conf`:
 
-   If you're using Docker:
+   ```toml
+   [crio.runtime.runtimes.crun-vm]
+   runtime_path = "/usr/bin/crun-vm"
+   ```
 
-     - Merge the following configuration into `/etc/docker/daemon.json`:
+3. Create a `RuntimeClass` object in the cluster that references crun-vm:
 
-       ```json
-       {
-         "runtimes": {
-           "crun-vm": {
-             "path": "/usr/local/bin/crun-vm"
-           }
-         }
-       }
-       ```
+   ```yaml
+   apiVersion: node.k8s.io/v1
+   kind: RuntimeClass
+   metadata:
+     name: crun-vm  # a name of your choice
+   handler: crun-vm
+   ```
 
-     - Reload the `docker` service for the new configuration to take effect:
+Pods can then be configured to use this `RuntimeClass` by specifying its name
+under `Pod.spec.runtimeClassName`.
 
-       ```console
-       $ service docker reload
-       ```
+See [4. Using crun-vm and **Pod YAML** to run a VM with **Podman**, **systemd**,
+or **Kubernetes**](4-pod-yaml.md) to get started.
 
-With Podman, it is possible to use crun-vm without installing it, *i.e.*,
-performing only steps 1–3 above. In this case, instead of setting the runtime
-with `--runtime crun-vm`, specify an absolute path to the runtime binary:
-`--runtime "$PWD"/target/debug/crun-vm`.
+[runtimes]: https://kubernetes.io/docs/setup/production-environment/container-runtimes/#cri-o
+[CRI-O]: https://cri-o.io/