particle-os/debian-forge-cli
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: update usage

Browse source 
Make sure to pass `--distro` so the `minimal-raw-xz` image type exists,
not all distributions have it and since we're available on multiple it's
better to be explicit.

Signed-off-by: Simon de Vlieger <supakeen@redhat.com>
This commit is contained in:
Simon de Vlieger 2025-07-31 10:42:38 +02:00
parent e7f44067b4
commit c38a24c780
2 changed files with 41 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

8
doc/00-installation.md
View file

@ -9,7 +9,7 @@ Install `image-builder` with the following command:
```console
$ sudo dnf install image-builder
# ...
$ sudo image-builder build minimal-raw
$ sudo image-builder build --distro fedora-42 minimal-raw-xz
# ...
```
@ -22,7 +22,7 @@ $ sudo dnf copr enable @osbuild/image-builder
# ...
$ sudo dnf install image-builder
# ...
$ sudo image-builder build minimal-raw
$ sudo image-builder build --distro fedora-42 minimal-raw-xz
# ...
```
@ -38,7 +38,7 @@ $ sudo podman run \
-it \
-v ./output:/output \
ghcr.io/osbuild/image-builder-cli:latest \
build minimal-raw
build --distro fedora-42 minimal-raw-xz
# ...
```
@ -54,5 +54,5 @@ $ git clone github.com/osbuild/image-builder-cli
$ cd image-builder-cli
$ go build ./cmd/image-builder
# ...
$ sudo ./image-builder build minimal-raw
$ sudo ./image-builder build --distro fedora-42 minimal-raw-xz
```

71
doc/01-usage.md
View file

@ -2,30 +2,33 @@
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.
Let's take a look at the available `x86_64` image types for Fedora 42 and build one of them.
```console
$ image-builder list --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
$ sudo image-builder build --distro fedora-41 qcow2
$ image-builder list --filter arch:x86_64 --filter distro:fedora-42
fedora-42 type:container arch:x86_64
fedora-42 type:iot-bootable-container arch:x86_64
fedora-42 type:iot-commit arch:x86_64
fedora-42 type:iot-container arch:x86_64
fedora-42 type:iot-installer arch:x86_64
fedora-42 type:iot-qcow2 arch:x86_64
fedora-42 type:iot-raw-xz arch:x86_64
fedora-42 type:iot-simplified-installer arch:x86_64
fedora-42 type:minimal-installer arch:x86_64
fedora-42 type:minimal-raw-xz arch:x86_64
fedora-42 type:minimal-raw-zst arch:x86_64
fedora-42 type:server-ami arch:x86_64
fedora-42 type:server-oci arch:x86_64
fedora-42 type:server-openstack arch:x86_64
fedora-42 type:server-ova arch:x86_64
fedora-42 type:server-qcow2 arch:x86_64
fedora-42 type:server-vagrant-libvirt arch:x86_64
fedora-42 type:server-vagrant-virtualbox arch:x86_64
fedora-42 type:server-vhd arch:x86_64
fedora-42 type:server-vmdk arch:x86_64
fedora-42 type:workstation-live-installer arch:x86_64
fedora-42 type:wsl arch:x86_64
$ sudo image-builder build --distro fedora-42 server-qcow2
# ...
```
@ -66,7 +69,7 @@ $ image-builder list --format=json | jq '.[0]'
To filter on a given distribution, one can use `--filter` with the `distro:` prefix:
```console
$ image-builder list --filter distro:fedora-41
$ image-builder list --filter distro:fedora-42
# ... long list ...
```
@ -92,7 +95,7 @@ $ image-builder list --filter arch:aarch64
Filters can be combined to narrow the list further.
```console
$ image-builder list --filter type:qcow2 --filter distro:fedora-41
$ image-builder list --filter type:qcow2 --filter distro:fedora-42
# ... list ...
```
@ -101,7 +104,7 @@ $ image-builder list --filter type:qcow2 --filter distro:fedora-41
The `build` command builds images of a given [image type](./10-faq.md#image-types), for example:
```console
$ sudo image-builder build minimal-raw
$ sudo image-builder build --distro fedora-42 minimal-raw-xz
# ... progress ...
```
@ -110,7 +113,7 @@ The `build` command requires root privileges in many cases as `image-builder` ne
By default the `build` command uses the same distribution and version as the host system, you can pass another distribution and version with the `--distro` argument:
```console
$ sudo image-builder build --distro fedora-43 minimal-raw
$ sudo image-builder build --distro centos-10 qcow2
# ... progress ...
```
@ -119,7 +122,7 @@ When passed `--arch` `image-builder` will try to do an experimental cross-archit
Cross-architecture builds are much slower than being able to build on native hardware. However, if no native hardware is available they might be an acceptable compromise.
```console
$ sudo image-builder build --arch s390x qcow2
$ sudo image-builder build --distro fedora-42 --arch s390x server-qcow2
WARNING: using experimental cross-architecture building to build "s390x"
# ... progress ...
```
@ -129,7 +132,7 @@ WARNING: using experimental cross-architecture building to build "s390x"
The `describe` command outputs structured information about an image without building it. It lists the packages that would be used to build the images and the partition tables.
```console
$ image-builder describe minimal-raw
$ image-builder describe minimal-raw-xz
@WARNING - the output format is not stable yet and may change
distro: fedora-43
type: minimal-raw-zst
@ -184,14 +187,14 @@ packages:
By default the `describe` command uses the same distribution and version as the host system, you can pass another distribution and version with the `--distro` argument:
```console
$ image-builder describe --distro fedora-43 minimal-raw
$ image-builder describe --distro fedora-43 minimal-raw-xz
# ... output ...
```
When passed `--arch` `image-builder` will show the description for that architecture:
```console
$ image-builder describe --arch aarch64 minimal-raw
$ image-builder describe --arch aarch64 minimal-raw-xz
# ... output ...
```
@ -200,21 +203,21 @@ $ image-builder describe --arch aarch64 minimal-raw
The `manifest` command outputs an [osbuild](https://github.com/osbuild/osbuild) manifest for an image. This manifest contains all the steps performed to assemble the eventual image but the image itself is not created.
```console
$ image-builder manifest minimal-raw
$ image-builder manifest minimal-raw-xz
# ... json ...
```
By default the `manifest` command uses the same distribution and version as the host system, you can pass another distribution and version with the `--distro` argument:
```console
$ image-builder manifest --distro fedora-43 minimal-raw
$ image-builder manifest --distro fedora-43 minimal-raw-xz
# ... json ...
```
When passed `--arch` `image-builder` will show the manifest for that architecture:
```console
$ image-builder manifest --arch aarch64 minimal-raw
$ image-builder manifest --arch aarch64 minimal-raw-xz
# ... output ...
```
@ -240,6 +243,6 @@ enabled = ["nginx", "haproxy"]
[[customizations.user]]
name = "user"
key = "ssh-ed25519 AAAAC..."
$ sudo image-builder build --blueprint blueprint.toml --distro fedora-41 qcow2
$ sudo image-builder build --blueprint blueprint.toml --distro fedora-42 server-qcow2
# ...
```