Koji

= Koji =

Koji is the software that builds RPM packages for the Fedora project. It uses Mock to create chroot environments for perform builds. To download the source code, report bugs, join the mailing list etc., see the Koji project website.

HowTos
Setting up and using Koji on Fedora:


 * Using the Koji build system
 * Run Your Own Koji Build Server
 * Building Images in Koji
 * Defining hub policies

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
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
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. Essentially kojid asks koji-hub for work. 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
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. It acts as a client to koji-hub providing a visual interface to preform a limited amount of administration. koji-web exposes a lot of information and also provides a means for certain operations, such as cancelling builds.

Koji-client
koji-client 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 adding users and initiating build requests.

Kojira
kojira is a daemon that keeps the build root repodata updated. It is responsible for removing redundant build roots and cleaning up after a build request is completed.

Tags and Targets
Koji organizes packages using tags:


 * 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:

$ koji list-targets

You can see just a single target with the --name option:

$ koji list-targets --name dist-fc7

Name                          Buildroot                      Destination - dist-fc7                      dist-fc7-build                 dist-fc7

This tells you a build for target dist-fc7 will use a buildroot with packages from the tag dist-fc7-build and tag the resulting packages as dist-fc7.

You can get a list of tags with the following command:

$ koji list-tags

Package lists
As mentioned above, each tag has its own list of packages that may be placed in the tag. To see that list for a tag, use the list-pkgs command:

$ koji list-pkgs --tag dist-fc7

Package                Tag                     Extra Arches     Owner --- --- ElectricFence           dist-fc6                                 pmachata GConf2                 dist-fc6                                 rstrode lucene                 dist-fc6                                 dbhole lvm2                   dist-fc6                                 lvm-team ImageMagick            dist-fc6                                 nmurray m17n-db                dist-fc6                                 majain m17n-lib               dist-fc6                                 majain MAKEDEV                dist-fc6                                 clumens [...]

The first column is the name of the package, the second tells you which tag the package entry has been inherited from, and the third tells you the owner of the package.

Latest Builds
To see the latest builds for a tag, use the latest-pkg command:

$ koji latest-pkg --all dist-fc7

Build                                    Tag                   Built by ConsoleKit-0.1.0-5.fc7                    dist-fc7              davidz ElectricFence-2.2.2-20.2.2               dist-fc6              jkeating GConf2-2.16.0-6.fc7                      dist-fc7              mclasen ImageMagick-6.2.8.0-3.fc6.1              dist-fc6-updates      nmurray MAKEDEV-3.23-1.2                         dist-fc6              nalin MySQL-python-1.2.1_p2-2                  dist-fc7              katzj NetworkManager-0.6.5-0.3.cvs20061025.fc7 dist-fc7              caillon ORBit2-2.14.6-1.fc7                      dist-fc7              mclasen

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 [...]

= Runs Here Also=

Koji is also know to be used in many places, Known koji installations. Feel free to add your own.