doc

doc/00-installation.md

@@ -0,0 +1,64 @@
+# Installation
+
+As `image-builder-cli` is still in development its packages are not yet included in any distribution. There are however multiple ways that you can already use it. After you have `image-builder-cli` installed take a look at its [usage](./01-usage.md).
+
+## Container
+
+We build a container for `x86` and `aarch64` from our main branch; you can use it like this. We need to use a privileged container due to the way filesystems work in Linux. The below command will build a Fedora 41 Minimal Raw disk image and put it into the mounted output directory.
+
+```
+€ sudo podman run \
+    --privileged \
+    -v ./output:/output \
+    ghcr.io/osbuild/image-builder-cli:latest \
+    --distro fedora-41 \
+    build minimal-raw
+# ...
+```
+
+## RPM
+
+If you're on a distribution that uses the RPM package format we also build RPMs from our main branch. These are hosted on COPR and you could use them:
+
+```
+€ sudo dnf copr enable @osbuild/image-builder-cli
+# ...
+€ sudo dnf install image-builder-cli
+# ...
+€ sudo image-builder build --distro fedora-41 minimal-raw
+# ...
+```
+
+## Go
+
+You can also run `image-builder-cli` directly with Go's package management.
+
+_Doing this requires the pre-installation of `osbuild-composer` from your distributions package manager._
+
+```
+€ sudo go run 'github.com/osbuild/image-builder-cli/cmd/image-builder@main' build --distro fedora-41 minimal-raw
+# ...
+```
+
+While not recommended you can also install `image-builder-cli` directly with Go:
+
+```
+€ sudo go install 'github.com/osbuild/image-builder-cli/cmd/image-builder'
+# ...
+€ sudo image-builder build --distro fedora-41 minimal-raw
+# ...
+```
+
+## Source
+
+Another option, and this might be most useful while hacking on the source is to run directly from a source checkout.
+
+_Doing this requires the pre-installation of `osbuild-composer` from your distributions package manager._
+
+
+```
+€ git clone github.com/osbuild/image-builder-cli
+# ...
+€ sudo go run ./cmd/image-builder --distro fedora-41 build minimal-raw
+# ...
+```

doc/01-usage.md

@@ -0,0 +1,58 @@
+# Usage
+
+After [installing](./00-installation.md) you probably want to use `image-builder-cli`. A general workflow would be to find the image type you want to build and then build it.
+
+Let's take a look at the available `x86_64` image types for Fedora 41 and build one.
+
+```
+€ image-builder list-images --filter arch:x86_64 --filter distro:fedora-41
+fedora-41 type:ami arch:x86_64
+fedora-41 type:container arch:x86_64
+fedora-41 type:image-installer arch:x86_64
+fedora-41 type:iot-bootable-container arch:x86_64
+fedora-41 type:iot-commit arch:x86_64
+fedora-41 type:iot-container arch:x86_64
+fedora-41 type:iot-installer arch:x86_64
+fedora-41 type:iot-qcow2-image arch:x86_64
+fedora-41 type:iot-raw-image arch:x86_64
+fedora-41 type:iot-simplified-installer arch:x86_64
+fedora-41 type:live-installer arch:x86_64
+fedora-41 type:minimal-raw arch:x86_64
+fedora-41 type:oci arch:x86_64
+fedora-41 type:openstack arch:x86_64
+fedora-41 type:ova arch:x86_64
+fedora-41 type:qcow2 arch:x86_64
+fedora-41 type:vhd arch:x86_64
+fedora-41 type:vmdk arch:x86_64
+fedora-41 type:wsl arch:x86_64
+€ image-builder build --distro fedora-41 qcow2
+# ...
+```
+
+# Blueprints
+
+Images can be customized with [blueprints](https://osbuild.org/docs/user-guide/blueprint-reference). For example we can build the `qcow2` we built above with some customizations applied.
+
+We'll be adding the `nginx`, and `haproxy` packages and enabling their services so they start on boot. We'll also add a user by the name `user` with an ssh key and set the hostname of the machine:
+
+```
+€ cat blueprint.toml 
+packages = [
+    { name = "nginx" },
+    { name = "haproxy" },
+]
+
+[customizations]
+hostname = "mynewmachine.home.arpa"
+
+[customizations.services]
+enabled = ["nginx", "haproxy"]
+
+[[customizations.user]]
+name = "user"
+key = "REDACTED"
+€ image-builder build --distro fedora-41 qcow2 blueprint.toml
+# ...
+```
+
+_Note that blueprints are aimed at end-user or systems administrator customizations. They take care to not break image builds and due to that they are not the right abstraction level for those who want to build or maintain entire distributions. For those interested in that usecase please take a look at the roadmap._

doc/10-faq.md

@@ -0,0 +1,7 @@
+# Frequently Asked Questions
+
+As we receive questions we'll fill in the frequent ones here.
+
+## Why does `image-builder-cli` need `root` permissions?
+
+For image types where we need to work with filesystems we need root. Mounting and working with filesystems is not namespaced in the Linux kernel and mounting filesystems is generally considered to be "running untrusted code in the kernel" hence it requires root permissions.

doc/index.md

@@ -0,0 +1,5 @@
+# image-builder-cli
+
+The `image-builder-cli` project provides a local entrypoint into the [Image Builder](https://osbuild.org/) ecosystem. It allows you to build various predefined images with [customizations](./01-usage.md#blueprints).
+
+For any questions you can take a look at our [FAQ](./10-faq.md) or the [GitHub issues](https://github.com/osbuild/image-builder-cli) and [GitHub discussions](https://github.com/orgs/osbuild/discussions). We're also available in the [#image-builder:fedoraproject.org](https://matrix.to/#/#image-builder:fedoraproject.org?web-instance%5Belement.io%5D=chat.fedoraproject.org) Matrix channel.