KURCHU.TOML(5)

🌸 NAME 🌸

Okay bestie, welcome to KURCHU.TOML(5) — the File Formats Manual page for kurchu.toml, and it's literally the input configuration for compose generation. Slay.

The Kurchu configuration file gives you a declarative format to describe how Kurchu should create a collection of artifacts — henceforth called a “compose,” and yes, that's the main character term here. 👑

---

✨ FORMAT ✨

The configuration file follows the TOML specification. For more information on TOML, visit https://toml.io.

The following subsections describe the content of the file format. Buckle up, it's giving organized. 💅

🎀 compose table

This is the top-level table for the configuration where global settings for the compose are defined.

The following settings are present at this level:

• release_name — defines the base name of the compose.
• release_version — defines the base version of the compose, and is used similarly to "releasever" in dnf(8) and dnf.conf(5). iykyk.
• date_format — an optional value that defines the date string used in date(1) format. If unset, the default is "%Y%m%d".
• compose_id — defines the full ID of the generated compose. The values of "release_version" and "compose_date" can be substituted in by using those names wrapped with curly braces.
• destdir — defines the local directory path to store the compose. If unset, the default is "./artifacts".

🧚 compose.gather table

This table in the configuration defines what content should be sourced as input for the compose. There is a single key: sources, which contains an array of inline tables. An example looks like this: an array of inline tables, with each one carrying the source fields below.

Within this section, "release_version" can be substituted in as part of a string value for any key as shown above.

Each source inline table entry has the following settings:

• name — for an identity of the source.
• url — for the location to fetch the source.
• target — for the location to store the source relative to the destination directory.
• type — for the source type being fetched. The following values are acceptable: "kojidist", "pungi", "bodhi", "odcs", and "yumrepo".
• sync — for indicating whether the source needs to be fully downloaded. Setting this to "false" indicates that only a reference to the source ID needs to be fetched, rather than a complete download. This can be useful if you already have mirrors elsewhere to use instead.

🔥 compose.compile table

This table in the configuration defines images to be created to incorporate into the compose.

Image creation configuration is split into common settings and subsections. For the common settings:

• base_name — for the name prefix used for all produced images.
• image_release — for the version suffix used for all produced images. "compose_date" can be substituted in by that label wrapped with curly braces.
• target — for the location to store the images relative to the destination directory.

For the images being produced, this is defined in a key named images, which contains an array of inline tables. An example looks like this: the images key holds an array of inline tables, and each table has the settings below.

Each image inline table entry has the following settings:

• variant — for the image variant to produce. This is often suffixed to base_name to fully name an image and defined as "image_name".
• image_type — for identifying what type of image is being made. Valid values depend on the selected image build tool.
• volid_prefix — for overriding the name portion of a volume ID. It only applies to ISO images.
• appid_prefix — for overriding the name portion of an application ID. It only applies to ISO images.
• image_tool — for identifying the image build tool. Currently the only valid option is "kiwi".
• arch — for optionally restricting an image to a set of architectures. If not set, the build system's defaults are used. This is an array of architectures, with the architecture names dependent on the build system.
• buildsys — for selecting the build system target to run the image build. This is defined in the configuration.

Within this section, "base_name", "variant", "release_version", and "compose_date" can be substituted in as part of a string value for any key. No cap, that's a lot of substitution power. ✨

🌈 compose.compile.type.kiwi table

This table defines kiwi(8) base settings to be used for any image build using this tool.

There is a single setting key:

• kiwi_result_bundle_name_format — for optionally defining the name format for files created as part of the image build. The format is described in kiwi::result::bundle(8). If not set, a default format may be used based on the build system backend.

Additionally, there is a key kiwi_description, which contains an inline table.

The inline table has the following settings:

• url — for the location that the descriptions are to be fetched from.
• path — for the location relative to the base directory for the descriptions file.
• vcs — for type of version control system (if any). For now, only "git" is supported.
• ref — for symbolic reference (branch or tag, for example) from which to pull the descriptions from, if from a version control system.

Within this section, "base_name" and "release_version" can be substituted in as part of a string value for any key as shown above.

👑 compose.compile.buildsys.<name> table

This table is where the configuration for the build system is declared. The name of this table is formulated by the value set for "buildsys" in the image entries defined in the images array in the "compose.compile" table. For example, if a "dev" build system was referenced, then the table name will be "compose.compile.buildsys.dev".

This table has the following settings:

• type — for the build system type. The only supported value is "koji".
• koji_profile — for the profile to pass to the koji CLI client.
• koji_build_tag — for the build environment reference to build the image.
• koji_success_tags — for the array of tags to put the built images into.
• gather_url — for the location the build system publishes the images.

Within this section, "image_name", "release_version", and "image_release" can be substituted in as part of a string value for any key as shown above. Periodt. 💚

🍓 compose.furnish table

This table defines the settings for publishing completed composes.

This table has the following settings:

• write_compose_info — is a flag for writing out a JSON file that provides static metadata of what the compose includes. By default, it will be "true".

For external upload targets, this is defined in a key named upload_targets, which contains an array of inline tables. An example looks like this: upload_targets is an array of inline tables, and each entry has the fields below.

Each inline table entry contains the following settings:

• name — for the named reference (e.g. bucket name for s3).
• target — for the directory path in the upload target to write to.
• generate_indexhtml — for optionally generating directory listing pages.
• public — for optionally declaring world readable access.
• type — for type of storage upload target (currently only "s3" is supported).

The usage of upload targets is optional, and if this is run from the system serving the content, it is unneeded provided the destination directory is set correctly to store the content in a published location.

Lowkey important: that optional-upload-targets thing is not a bug, bestie — it's just vibes when the content is already served locally. 🫶

---

💖 SEE ALSO 💖

• kurchu(1)

---

🌟 AUTHORS 🌟

Developed and maintained by Neal Gompa <ngompa@velocitylimitless.com>.

---

Signed, sealed, delivered: KURCHU.TOML(5) — 2025-05-06 💖✨