Koji HOWTO — Koji 1.35.1 documentation (2024)

The web interface¶

The primary interface for viewing Koji data is a web application. Mostof the interface is read-only, but if you are logged in (see below) andhave sufficient privileges there are some actions that can be performedthough the web. For example:

• Cancel a build

• Resubmit a failed task

  See Also

  The Unconventional Guide to Colors In PythonWriting Koji Code — Koji 1.16.0 documentationWritingKojiCode - Fedora Project WikiWriting Koji Code — Koji 1.35.1 documentation

Those with admin privileges will find additional actions, such as:

• Create/Edit/Delete a tag

• Create/Edit/Delete a target

• Enable/Disable a build host

The web site utilizes Kerberos authentication. In order to log in youwill need a valid Kerberos ticket and your web browser will need to beconfigured to send the Kerberos information to the server.

In Firefox, you will need to use the about:config page to seta Kerberos parameter. Use the search term ‘negotiate’ to filter the list.Change network.negotiate-auth.trusted-uris to the domain you want toauthenticate against, e.g .example.com. You can leavenetwork.negotiate-auth.delegation-uris blank, as it enables Kerberosticket passing, which is not required.

In order to obtain a Kerberos ticket, use the kinit command.

Installing the Koji cli¶

There is a single point of entry for most operations. The command iscalled ‘koji’ and is included in the main koji package.

The koji tool authenticates to the central server using Kerberos, so youwill need to have a valid Kerberos ticket to use many features. However,many of the read-only commands will work without authentication.

Building a package¶

Builds are initiated with the command line tool. To build a package, thesyntax is:

$ koji build <build target> <git URL>

For example:

$ koji build f25 git://pkgs.fedoraproject.org/rpms/eclipse-jgit?#00ca55985303b1ce19c632922ebcca283ab6e296

The koji build command creates a build task in Koji. By default thetool will wait and print status updates until the build completes. Youcan override this with the --nowait option. To view other options tothe build command use the --help option.

$ koji build --help

Build Options¶

There are a few options to the build command. Here are some moredetailed explanations of them:

--skip-tag

Normally the package is tagged after the build completes. Thisoption causes the tagging step to be skipped. The package will be inthe system, but untagged (you can later tag it with the tag-buildcommand)

--scratch

This makes the build into a scratch build. The build will not beimported into the db, it will just be built. The rpms will landunder <topdir>/scratch. Scratch builds are not tracked and can neverbe tagged, but can be convenient for testing. Scratch builds aretypically removed from the filesystem after one week.

--nowait

As stated above, this prevents the cli from waiting on the buildtask.

--arch-override

This option allows you to override the base set of arches to buildfor. This option is really only for testing during the beta period,but it may be retained for scratch builds in the future.

See Also

How to write Koji plugins — Koji 1.16.0 documentation

Build Failures¶

If your package fails to build, you will see something like this.

420066 buildArch (kernel-2.6.18-1.2739.10.9.el5.jjf.215394.2.src.rpm,ia64): open (build-1.example.com) -> FAILED: BuildrootError:error building package (arch ia64), mock exited with status 10

You can figure out why the build failed by looking at the log files. Ifthere is a build.log, start there. Otherwise, look at init.log

$ ls -1 <topdir>/work/tasks/420066/*<topdir>/work/tasks/420066/build.log<topdir>/work/tasks/420066/init.log<topdir>/work/tasks/420066/mockconfig.log<topdir>/work/tasks/420066/root.log

Terminology¶

In Koji, it is sometimes necessary to distinguish between the a packagein general, a specific build of a package, and the various rpm filescreated by a build. When precision is needed, these terms should beinterpreted as follows:

Package

The name of a source rpm. This refers to the package in general andnot 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. Forexample: 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-RPCserver running under mod_wsgi in Apache. koji-hub is passive inthat it only receives XML-RPC calls and relies upon the build daemonsand other components to initiate communication. koji-hub is the onlycomponent that has direct access to the database and is one of thetwo 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 andhandling them accordingly. Koji also has support for tasks other thanbuilding. Creating install images is one example. kojid isresponsible for handling these tasks as well.

  kojid uses mock for building. It also creates a fresh buildroot forevery build. kojid is written in Python and communicates withkoji-hub via XML-RPC.

• koji-web is a set of scripts that run in mod_wsgi and use theCheetah templating engine to provide an web interface to Koji.koji-web exposes a lot of information and also provides a means forcertain 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 performactions 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 analogousto 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 itshould be tagged afterwards. This allows target names to remain fixed astags change through releases. You can get a full list of build targetswith the following command:

$ koji list-targets

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

$ koji list-targets --name dist-fc7Name Buildroot Destination---------------------------------------------------------------------------------------------dist-fc7 dist-fc7-build dist-fc7

This tells you a build for target dist-fc7 will use a buildroot withpackages from the tag dist-fc7-build and tag the resulting packages asdist-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 beplaced in the tag. To see that list for a tag, use the list-pkgscommand:

$ koji list-pkgs --tag dist-fc7Package Tag Extra Arches Owner----------------------- ----------------------- ---------------- ----------------ElectricFence dist-fc6 pmachataGConf2 dist-fc6 rstrodelucene dist-fc6 dbholelvm2 dist-fc6 lvm-teamImageMagick dist-fc6 nmurraym17n-db dist-fc6 majainm17n-lib dist-fc6 majainMAKEDEV dist-fc6 clumens...

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

Latest Builds

To see the latest builds for a tag, use the latest-build command:

$ koji latest-build --all dist-fc7Build Tag Built by---------------------------------------- -------------------- ----------------ConsoleKit-0.1.0-5.fc7 dist-fc7 davidzElectricFence-2.2.2-20.2.2 dist-fc6 jkeatingGConf2-2.16.0-6.fc7 dist-fc7 mclasenImageMagick-6.2.8.0-3.fc6.1 dist-fc6-updates nmurrayMAKEDEV-3.23-1.2 dist-fc6 nalinMySQL-python-1.2.1_p2-2 dist-fc7 katzjNetworkManager-0.6.5-0.3.cvs20061025.fc7 dist-fc7 caillonORBit2-2.14.6-1.fc7 dist-fc7 mclasen

The output gives you not only the latest builds, but which tag they havebeen inherited from and who built them (note: for builds imported frombeehive the “built by” field may be misleading)

Exploring Koji¶

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

$ koji helpKoji commands are: build Build a package from source cancel-task Cancel a task help List available commands latest-build Print the latest builds for a tag...$ koji build --helpusage: 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...