doc: initial documentation

Supply initial documentation for `image-builder`. This documentation
will be imported into the osbuild [1] website.

[1]: https://osbuild.org/

Signed-off-by: Simon de Vlieger <supakeen@redhat.com>

.spellcheck-en-custom.txt

@@ -18,3 +18,17 @@ SBOM
 SBOMs
 spdx
 toml
+customizations
+entrypoint
+fedoraproject
+filesystems
+namespaced
+untrusted
+hostname
+roadmap
+COPR
+pre
+amongst
+RHEL
+hyperscalers
+weldr

README.md

@@ -37,15 +37,15 @@ We plan to provide rpm packages in fedora as well.
 You can compile the application in `cmd/image-builder` with
 the normal `go` command or use
 
-```
-make build
+```console
+$ make build
 ```
 
 To compile without go build tags you will need to install
 the required RPMs:
 
 ```console
-sudo dnf install gpgme-devel
+$ sudo dnf install gpgme-devel
 ```
 
 ## Prerequisites
@@ -171,10 +171,8 @@ $ image-builder list-images --output=json
     }
   }
 ]
-
 ```
 
-
 ## FAQ
 
 Q: Does this require a backend.

doc/00-installation.md

@@ -0,0 +1,59 @@
+# Installation
+
+`image-builder` packages are available in [Fedora](https://fedoraproject.org). You can also get a copy from other places listed here. After you have `image-builder` installed take a look at its [usage](./01-usage.md).
+
+## Fedora
+
+Install `image-builder` with the following command:
+
+```console
+$ sudo dnf install image-builder
+# ...
+$ sudo image-builder build minimal-raw
+# ...
+```
+
+## COPR
+
+If you want to get a more recent version of `image-builder` you can enable the [COPR](https://copr.fedorainfracloud.org/) repository, this provides builds from the `main` branch.
+
+```console
+$ sudo dnf copr enable @osbuild/image-builder
+# ...
+$ sudo dnf install image-builder
+# ...
+$ sudo image-builder build --distro fedora-41 minimal-raw
+# ...
+```
+
+## Container
+
+We build a container for the `x86_64` and `aarch64` architectures directly from our `main` branch. We need to run 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.
+
+```console
+$ mkdir output
+$ sudo podman run \
+    --privileged \
+    --rm \
+    -it \
+    -v ./output:/output \
+    ghcr.io/osbuild/image-builder-cli:latest \
+    --distro fedora-41 \
+    build minimal-raw
+# ...
+```
+
+## Source
+
+Another option, and this might be most useful while hacking on the source is to run directly from a source checkout.
+
+```console
+$ sudo dnf install go git-core osbuild osbuild-depsolve-dnf osbuild-ostree osbuild-lvm2 osbuild-luks2
+# ...
+$ git clone github.com/osbuild/image-builder-cli
+# ...
+$ cd image-builder-cli
+$ go build ./cmd/image-builder build
+# ...
+$ sudo ./image-builder --distro fedora-41 minimal-raw
+```

doc/01-usage.md

@@ -0,0 +1,56 @@
+# Usage
+
+After [installation](./00-installation.md) you probably want to use `image-builder`. 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 of them.
+
+```console
+$ 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 could 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:
+
+```console
+$ cat blueprint.toml
+packages = [
+    { name = "nginx" },
+    { name = "haproxy" },
+]
+
+[customizations]
+hostname = "mynewmachine.home.arpa"
+
+[customizations.services]
+enabled = ["nginx", "haproxy"]
+
+[[customizations.user]]
+name = "user"
+key = "ssh-ed25519 AAAAC..."
+$ sudo image-builder build --blueprint blueprint.toml --distro fedora-41 qcow2
+# ...
+```

doc/10-faq.md

@@ -0,0 +1,17 @@
+# Frequently Asked Questions
+
+As we receive questions we'll fill in the frequent ones here.
+
+## How does `image-builder` fit into the Image Builder ecosystem?
+
+The Image Builder team provides a bunch of tools that people can use to build, define, and customize operating system images. Amongst those are:
+
+1. The [Image Builder service]() on the [Red Hat Console]() which lets users build images through an API or user interface, automatically upload images to their favorite hyperscalers. It integrates there with various other services such as custom content.
+2. [osbuild-composer]() is the component that provides APIs for the [Image Builder service]() in such a way that you can host them locally.
+3. [weldr-client]() is an application that uses the [osbuild-composer]() provided APIs to offer a local command line program to start, stop, and manage builds.
+
+The above can be quite confusing, hence we've created `image-builder`. It allows you to do the same things as [weldr-client]() except it does so without the need to run [osbuild-composer](). Builds are done directly without going through other layers. This makes [image-builder]() easier to install and use in a lot of environments.
+
+## Why does `image-builder` 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
+
+The `image-builder` project provides image building with [user customizations](./01-usage.md#blueprints) for a variety of predefined operating systems like Fedora, CentOS, and RHEL.
+
+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.