| parent | nav_order |
|---|---|
Composing images |
1 |
{: .no_toc }
- TOC {:toc}
With rpm-ostree compose you get a tool to compose your own ostree commits based on a
treefile configuration, a couple of RPMs,
some post-processing and possibly some custom modifications directly in the resulting tree.
The tool allows to either build a tree commit in one go with a single command: rpm-ostree compose tree.
Or to split that process up into smaller chunks with the usage of rpm-ostree compose install,
followed by rpm-ostree compose postprocess and finally rpm-ostree compose commit. While
the former approach is pretty complete and allows most use-cases the latter is useful if you need
some more customization on the resulting filesystem. More customization than the sandboxed
post-process functionality of the treefile allows.
In most scenarios you'll want to consider using a more "high level" tool, than rpm-ostree compose.
Originally rpm-ostree compose tree was intended to be a "high level" tool,
but that didn't work out very well in practice. Today, you should consider
it as a low level tool. For example, most people that want to generate
OSTree commits also want to generate bootable disk images, and rpm-ostree
has nothing to do with that.
One example higher level tool that takes care of both OSTree commit generation and bootable disk images is coreos-assembler; it is strongly oriented towards "CoreOS-like" systems which include rpm-ostree and Ignition.
The osbuild project has some support for rpm-ostree based systems. See this blog entry for example.
Before you get started, it's recommended to read (at least) these two sections of the OSTree manual:
Currently, rpm-ostree is fairly coupled to the Fedora project. We are open to supporting other distributions however.
Example base rpm-ostree "manifest repositories" are:
This program takes as input a manifest file that describes the target system, and commits the result to an OSTree repository.
The input format is a YAML (or JSON) "treefile".
If you're doing this multiple times, it's strongly recommended to create a cache directory:
# rpm-ostree compose tree --unified-core --cachedir=cache --repo=./build-repo /path/to/manifest.yaml
This will download RPMs from the referenced repos, and commit the result to the
OSTree repository, using the ref named by ref.
Once we have that commit, let's export it:
# ostree --repo=/srv/deploy-repo pull-local ./build-repo exampleos/8/x86_64/stable
You can tell client systems to rebase to it by combining ostree remote add,
and rpm-ostree rebase on the client side.
In order to get even more control we split rpm-ostree compose tree into
rpm-ostree compose install, followed by rpm-ostree compose postprocess
and finally rpm-ostree compose commit.
Similar to rpm-ostree compose tree we'll use a "treefile". We'll also specify a target directory
serving as our work-in-progress rootfs:
# rpm-ostree compose install --unified-core --cachedir=cache --repo=./build-repo /path/to/manifest.yaml ./sysroot
This will download RPMs from the referenced repos and execute any specified post-process scripts.
We now can alter anything found under ./sysroot/rootfs.
Next we can run more postprocessing:
# rpm-ostree compose postprocess ./sysroot/rootfs /path/to/manifest.yaml
When we are finished with our manual changes we can now create the commit:
# rpm-ostree compose commit --repo=./build-repo /path/to/manifest.yaml ./sysroot/rootfs
Once we have that commit, let's export it:
# ostree --repo=/srv/deploy-repo pull-local ./build-repo exampleos/8/x86_64/stable
You can tell client systems to rebase to it by combining ostree remote add,
and rpm-ostree rebase on the client side.
rpm-ostree compose tree runs well in an unprivileged (or "run as root")
podman container. You can also use other container tools, they are just less
frequently tested.
You can also directly install rpm-ostree on a traditional yum/rpm based
virtual (or physical) machine - it won't affect your host. However, containers
are encouraged.