https://github.com/osbuild/image-builder-cli
Building operating system artifacts (disk images, ISOs, etc.)
https://github.com/osbuild/image-builder-cli
Last synced: 6 months ago
JSON representation
Building operating system artifacts (disk images, ISOs, etc.)
- Host: GitHub
- URL: https://github.com/osbuild/image-builder-cli
- Owner: osbuild
- License: apache-2.0
- Created: 2024-11-12T08:42:53.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-16T08:22:34.000Z (over 1 year ago)
- Last Synced: 2025-04-16T11:01:44.774Z (over 1 year ago)
- Language: Go
- Homepage: https://osbuild.org
- Size: 306 KB
- Stars: 5
- Watchers: 8
- Forks: 10
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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-43 \
minimal-raw
```
## Installation
You can install `image-builder` in Fedora and CentOS from the repositories:
```console
$ dnf install image-builder
```
As this project is under development right now we provide up-to-date
development snapshots of the main branch through COPR:
```console
$ dnf copr enable @osbuild/image-builder
$ dnf install image-builder
```
You can also install `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
```
Lastly you can use a container:
```console
$ sudo podman run --privileged ghcr.io/osbuild/image-builder-cli
```
When building an image in the container it will be written to `/output` in the container. If you want the produced images available on your host system mount that directory:
```console
$ mkdir output
$ sudo podman run --privileged -v ./output:/output ghcr.io/osbuild/image-builder-cli
```
## 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
...
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
...
```
### Adding registrations
Adding registrations/subscriptions to an image can be done at
build time via the `--registrations` command line option. When
using this option the resulting image will include the given
subscriptions/registrations in the resulting image.
Currently the Red Hat subscription is supported, e.g.
```console
$ cat > registrations.json </repositories directory for a file called .json
that contains the repositories for the .
This .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 `, 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.
When replacing repositories with Katello/Satellite kickstart trees, make sure
to use HTTP URL instead of HTTPS because there is no entitlement certificate
available during the build. Also, keep in mind that GPG check is disabled when
overriding base repositories. To use GPG, use `--data-dir` instead.
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-43 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.
## Subscriptions
When executing `image-builder-cli` via `podman`, subscription information is
passed to the container and used to access Red Hat CDN. As long as the host
machine is properly subscribed with attached Red Hat Enterprise Linux
subscription, building RHEL images will work automatically.
To use content from Red Hat Satellite, follow the extra repositories section
above.
## 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 "-.json",
files, e.g. "fedora-43.json". See these [examples](https://github.com/osbuild/images/tree/main/data/repositories). Use the "--force-data-dir" switch and
place them under "repositories/name-version.json", e.g. for:
"--force-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.
Q: I get `Warnings during manifest creation` and the build stops, what can I do?
A: This is a safety feature so that in e.g. CI systems warnings cannot
go unnoticed. Just add `--ignore-warnings` to the build they are
harmless.
## Project
* **Website**:
* **Bug Tracker**:
* **Discussions**:
* **Matrix (chat)**: [Image Builder channel on Fedora Chat](https://matrix.to/#/#image-builder:fedoraproject.org?web-instance[element.io]=chat.fedoraproject.org)
* **Changelog**:
### Repository
- **web**:
- **https**: `https://github.com/osbuild/image-builder-cli.git`
- **ssh**: `git@github.com:osbuild/image-builder-cli.git`