HowTos

Koji Architecture

Terminology

In Koji it is sometimes necessary to distinguish between a package in general, a specific build of a package, and the various rpm files created by a build. When precision is needed, these terms should be interpreted as follows:

Package

The name of a source rpm. This refers to the package in general and not any particular build or subpackage. For example: kernel, glibc, etc.

Build

A particular build of a package. This refers to the entire build: all arches and subpackages. For example: kernel-2.6.9-34.EL, glibc-2.3.4-2.19.

RPM

A particular rpm. A specific arch and subpackage of a build. For example: kernel-2.6.9-34.EL.x86_64, kernel-devel-2.6.9-34.EL.s390, glibc-2.3.4-2.19.i686, glibc-common-2.3.4-2.19.ia64

Koji Components

Koji is comprised of several components:

koji-hub is the center of all Koji operations. It is an XML-RPC server running under mod_python in Apache. koji-hub is passive in that it only receives XML-RPC calls and relies upon the build daemons and other components to initiate communication. koji-hub is the only component that has direct access to the database and is one of the two components that have write access to the file system.

kojid is the build daemon that runs on each of the build machines. Its primary responsibility is polling for incoming build requests and handling them accordingly. Koji also has support for tasks other than building. Creating install images is one example. kojid is responsible for handling these tasks as well. kojid uses mock for building. It also creates a fresh buildroot for every build. kojid is written in Python and communicates with koji-hub via XML-RPC.

koji-web is a set of scripts that run in mod_python and use the Cheetah templating engine to provide a web interface to Koji. koji-web exposes a lot of information and also provides a means for certain operations, such as cancelling builds.

koji is a CLI written in Python that provides many hooks into Koji. It allows the user to query much of the data as well as perform actions such as build initiation.

kojira is a daemon that keeps the build root repodata updated.

Package Organization

Tags and Targets

Koji organizes packages using tags. In Koji a tag is roughly analogous to a beehive collection instance, but differ in a number of ways:

Tags are tracked in the database but not on disk

Tags support multiple inheritance

Each tag has its own list of valid packages (inheritable)

Package ownership can be set per-tag (inheritable)

Tag inheritance is more configurable

When you build you specify a target rather than a tag

A build target specifies where a package should be built and how it should be tagged afterwards. This allows target names to remain fixed as tags change through releases. You can get a full list of build targets with the following command:

The output gives you not only the latest builds, but which tag they have been inherited from and who built them (note: for builds imported from beehive the "built by" field may be misleading).

Documentation

We've tried to make Koji self-documenting wherever possible. The command line tool will print a list of valid commands and each command supports --help. For example:

$ koji help
Koji commands are:
build Build a package from source
cancel-task Cancel a task
help List available commands
latest-build Print the latest rpms for a tag
latest-pkg Print the latest builds for a tag
[...]

$ koji build --help
usage: koji build [options] tag URL
(Specify the --help global option for a list of other help options)
options:
-h, --help show this help message and exit
--skip-tag Do not attempt to tag package
--scratch Perform a scratch build
--nowait Don't wait on build
[...]

You can see administrator-only command help with --admin. Most users will never use these additional commands, but if you're setting up your own Koji system, you may find them very useful.

$koji help --admin
Available commands:
add-external-repo Create an external repo and/or add one to a tag
add-group Add a group to a tag
add-group-pkg Add a package to a group's package listing
[...]