debian-forge-cli/README.md

# image-builder CLI

Build images from the command line in a convenient way.

## Run via container

```console
$ sudo podman run --privileged \
   -v ./output:/output \
   ghcr.io/osbuild/image-builder-cli:latest \
   build \
   --distro fedora-41 \
   minimal-raw
```

## Installation

This project is under development right now and we provide up-to-date
development snapshots in the following way:

A COPR RPM build
https://copr.fedorainfracloud.org/coprs/g/osbuild/image-builder/

Via the go build system:
```console
$ go run github.com/osbuild/image-builder-cli/cmd/image-builder@main
```
or install it into `$GOPATH/bin`
```console
$ go install github.com/osbuild/image-builder-cli/cmd/image-builder@main
```

We plan to provide rpm packages in fedora as well.

## Compilation

You can compile the application in `cmd/image-builder` with
the normal `go` command or use

```console
$ make build
```

To compile without go build tags you will need to install
the required RPMs:

```console
$ sudo dnf install gpgme-devel
```

## Prerequisites

Make sure to have the required `osbuild` RPMs installed:
```console
$ sudo dnf install osbuild osbuild-depsolve-dnf
```

## Examples

### Listing

To see the list of buildable images run:
```console
$ image-builder list-images
...
centos-9 type:qcow2 arch:x86_64
...
rhel-10.0 type:ami arch:x86_64
...
```

### Building

To actually build an image run:
```console
$ sudo image-builder build qcow2 --distro centos-9
...
```
this will create a directory `centos-9-qcow2-x86_64` under which the
output is stored.

With the `--with-manifest` option an
[osbuild](https://github.com/osbuild/osbuild) manifest will be
placed in the output directory too.

With the `--with-sbom` option an SPDX SBOM document will be
placed in the output directory too.

### Blueprints

Blueprints are supported, first create a `config.toml` and put e.g.
the following content in:
```toml
[[customizations.user]]
name = "alice"
password = "bob"
key = "ssh-rsa AAA ... user@email.com"
groups = ["wheel"]
```
Note that both toml and json are supported for the blueprint format.

See https://osbuild.org/docs/user-guide/blueprint-reference/ for
the full blueprint reference.

Then just pass them as an additional argument after the image type:
```console
$ sudo image-builder build qcow2 --blueprint ./config.toml --distro centos-9
...
```

### SBOMs

It is possible to generate spdx based SBOM (software bill of materials)
documents as part of the build. Just pass `--with-sbom` and
it will put them into the output directory.

### Cloud integration

When building an image type that can be uploaded to the cloud
(e.g. an "ami") image-builder will automatically upload if
all cloud parameters are provided, e.g.
```
$ image-builder build ami --distro centos-9 \
    --aws-region us-east-1 \
	--aws-bucket example-bucket \
	--aws-ami-name my-image-1
```
Images can also be uploaded with the `image-builder upload` command
after they are built.



### Filtering

When listing images, it is possible to filter:
```console
$ image-builder list-images --filter ami
...
centos-9 type:ami arch:x86_64
...
rhel-8.5 type:ami arch:aarch64
...
rhel-10.0 type:ami arch:aarch64
```
or be more specific
```console
$ image-builder list-images --filter "arch:x86*" --filter "distro:*centos*"
centos-9 type:ami arch:x86_64
...
centos-9 type:qcow2 arch:x86_64
...
```

The following filters are currently supported, shell-style globbing is supported:
 * distro: the distro name (e.g. fedora-41)
 * arch: the architecture name (e.g. x86_64)
 * type: the image type name (e.g. qcow2)
 * bootmode: the bootmode (legacy, UEFI, hybrid)

### Output control

The output can also be switched, supported are "text", "json":
```console
$ image-builder list-images --output=json
[
  {
    "distro": {
      "name": "centos-9"
    },
    "arch": {
      "name": "aarch64"
    },
    "image_type": {
      "name": "ami"
    }
  },
...
  {
    "distro": {
      "name": "rhel-10.0"
    },
    "arch": {
      "name": "x86_64"
    },
    "image_type": {
      "name": "wsl"
    }
  }
]
```

## Modifying the set of used repositories

There are various ways to add extra repositories or override the default
base repositories. Most users will want to use the
[blueprint systems](https://osbuild.org/docs/user-guide/blueprint-reference/#repositories)
for this. Repositories that are part of the blueprint will get added
to the installed image but are not used at build time to install third-party
packages.

To change repositories during image build time the command line options
`--data-dir`, `--extra-repo` and `--force-repo` can be used. The repositories
there will only added during build time and will not be available in the
installed system (use the above blueprint options if that the goal).

Note that both options are targeting advanced users/use-cases and when
used wrongly can result in failing image builds or non-booting
systems.

## Using the data-dir switch

When using the `--data-dir` flag `image-builder` will look into
the <datadir>/repositories directory for a file called <distro>.json
that contains the repositories for the <distro>.

This <distro>.json file is a simple architecture-> repositories mapping
that looks like [this example](https://github.com/osbuild/images/blob/main/data/repositories/centos-10.json).

### Adding extra repositories during the build

To add one or more extra repositories during the build use:
`--extra-repo <baseurl>`, e.g. `--extra-repo file:///path/to/repo`.
This will make the content of the repository available during image
building and the dependency solver will pick packages from there as
appropriate (e.g. if that repository contains a libc or kernel with a
higher version number it will be picked over the default
repositories).

### Overriding the default base repositories during build

To completely replace the default base repositories during a build the
option `--force-repo=file:///path/to/repos` can be used.

Note that the repositories defined there will be used for all
dependency solving and there is no safeguards, i.e. one can point to
a fedora-42 repository url and try to build a centos-9 image type and
the system will happily try its best (and most likely fail). Use with
caution.


## FAQ

Q: Does this require a backend.
A: The osbuild binary is used to actually build the images but beyond that
   no setup is required, i.e. no daemons like osbuild-composer.

Q: Can I have custom repository files?
A: Sure! The repositories are encoded in json in "<distro>-<vesion>.json",
   files, e.g. "fedora-41.json". See these [examples](https://github.com/osbuild/images/tree/main/data/repositories). Use the "--data-dir" switch and
   place them under "repositories/name-version.json", e.g. for:
   "--data-dir ~/my-project --distro foo-1" a json file must be put under
   "~/my-project/repositories/foo-1.json.

Q: What is the relation to [bootc-image-builder](https://github.com/osbuild/bootc-image-builder)?
A: Both projects are very close. The `bootc-image-builder` focuses on providing
   image-based artifacts while `image-builder` works with traditional package
   based inputs. We expect the two projects to merge eventually and they already
   share a lot of code.

## Project

 * **Website**: <https://www.osbuild.org>
 * **Bug Tracker**: <https://github.com/osbuild/image-builder-cli/issues>
 * **Discussions**: <https://github.com/orgs/osbuild/discussions>
 * **Matrix (chat)**: [Image Builder channel on Fedora Chat](https://matrix.to/#/#image-builder:fedoraproject.org?web-instance[element.io]=chat.fedoraproject.org)
 * **Changelog**: <https://github.com/osbuild/image-builder-cli/releases>

### Repository

 - **web**:   <https://github.com/osbuild/image-builder-cli>
 - **https**: `https://github.com/osbuild/image-builder-cli.git`
 - **ssh**:   `git@github.com:osbuild/image-builder-cli.git`