Free as in sake: The story of Koji

No readers like this yet.
open source button on keyboard

Koji is an open source build system. While many are familiar with Koji because of the Fedora Project's use of it, Koji is a generic system that is used by different groups around the world.

What is Koji?

Since the term "build system" means different things to different folks, let me explain a bit about what Koji does. From the developer's perspective, Koji is a service that accepts build requests and farms them out to different machines for building. Koji tracks the resulting packages in its database and supports a robust tagging system for organizing them. Koji has a web interface, a command line interface, and a rich XML-RPC interface. Originally Koji was limited to building RPMs, but now it also supports building Java packages via Maven. It also has features for building livecd and appliance images from other content in the system.

When Koji builds an RPM it first creates a pristine chroot environment, a buildroot, in which to perform the build. The contents of this buildroot are other packages from Koji's database, starting with a common base set and including additional packages to satisfy build dependencies. To do this, Koji uses another open source tool called Mock. Using Mock gives us consistent, reproducible build environments. It also means that users can replicate those environments on their own systems, which is helpful for debugging build issues.

For Java packages the process is similar. We start with a Mock-generated buildroot, but since Mock doesn't understand Java packages we use a tool called Maven to resolve those dependencies and perform the build inside the buildroot. As with RPMs, these dependencies are pulled from Koji's database.

Once completed, a build is imported into Koji's database and tagged. Koji's tagging system is very flexible and can support build configurations for many different projects in the same instance. For example the Fedora Project uses their Koji instance to build for all the currently supported Fedora versions, as well as rawhide and EPEL.

The early days

Koji began life as an internal Red Hat project. We had outgrown our existing build system and needed something more flexible and scalable. Experience (and frustration) with our two earlier systems shaped our goals and design.

At this time, Fedora was still split into two parts. Fedora Core, the main portion of the distribution, was created within Red Hat by Red Hat engineers. Fedora Extras, a collection of packages not found in Core, was developed outside of Red Hat's walls by a mix of Red Hat engineers and community volunteers. There were different tools, different processes, and a somewhat divided community.

While we were working on Koji, the Fedora community was also developing a build system for Fedora Extras (which would eventually be named Plague). Koji and Plague had different needs, but the core requirement of building RPMs in a buildroot was shared. This common need was met by Mock.

Even in these early days, we had community involvement through Mock and other related tools (such as createrepo). Code was shared in both directions. There wasn't much call to release Koji; it was an internal system tied to other internal systems. Fedora Extras had Plague, and Fedora Core was still built inside of Red Hat. In fact, Fedora Core 6 was built using an early internal version of Koji.

Freeing Koji

Then everything changed.

At the Fedora Summit following the release of FC6, a plan was hatched to merge Core and Extras. Ideas had been brewing for some time, but now it was official--the next release would simply be Fedora 7. The entire distribution would be created "in the community on open source tools."

Of course, this newly unified Fedora would need a build system and it quickly became apparent that Koji was the right tool for the job. While Fedora Extras was already using Plague, it did not satisfy the requirements for building the entire distribution. So, after much discussion, Red Hat released Koji under an open source license. Koji became a key part of Fedora's new end-to-end, free and open infrastructure.

Over time, other folks discovered Koji as well. Initially discussion on our mailing list was Fedora-centric, but soon we had other folks asking for help setting up their own instances. We've seen such questions coming from businesses, universities, research facilities, and community projects. If you're running a Fedora-derived project, or just performing a lot of builds for Fedora or a Fedora-like distribution, Koji is a natural choice.

Life in the open

Freeing Koji has been good for Fedora, good for Koji, and good for Red Hat. Fedora gained a robust and flexible build system, Koji gained a larger community of users and contributors, and Red Hat benefits from this success.

During the Core-Extras merger, being able to use Koji was a huge help to Fedora. While some integration work was required, all other options would have demanded much more effort. Red Hat had already been building pre-merger versions of Core in an early version of Koji, so the transition was simply less drastic. Furthermore, Koji's robust XML-RPC interface allowed other parts of Fedora infrastructure to tie in with relative ease. Over the past four years, Koji has shown its flexibility as Fedora's needs have changed.

At the same time, Koji has benefited both from being open source and from Fedora's use of it. All the standard benefits apply: more eyes on the code, patch submissions, additional testing, broader feedback, help with documentation, exposure to a wider variety of runtime conditions. Fedora has raised Koji's profile, giving more folks a reason to look at or use it.

All of this has made Koji /better/. The requirements of Fedora and other users in the community helped drive innovation in the system. A number of features might never have happened otherwise, or at least taken much longer: ssl certification authentication, external yum repositories, the plugin and theme frameworks, the SCM framework, and numerous createrepo optimizations.

Koji helps Fedora and Fedora helps Red Hat, but the benefits are more than transitive. Red Hat is a Koji user, so every upstream improvement makes our instances better. While large Koji systems like Red Hat's and Fedora's inevitably develop a number of customizations (integration tools, plugins, policies, and configuration), it is still Koji underneath and that similarity is helpful. It reduces the amount of gear shifting for our developers who work on both Fedora and internal projects, and it helps us adapt Fedora content for our internal development.

Notable installations include at Amazon, TomTom, and Caltech's multi-university, CERN-based project. See who else is using Koji.

Further reading

Mike McLean is lead developer for Koji.


My apologies and not to sound picky, but looking at the photo, I think the term is "kouji" (see and not "koji" (see

Yeah, perhaps someone who knew some Japanese (language) should have been asked before it was decided that Fedora's build system namesake should be the equivalent of 'orphan' (or any of the other unintended translations listed on that page).

I've wondered whether any of the prominent community package repositories for Fedora (rpmfusion, etc.) use Koji...

great headline.

Sorry guys, but Koji is far inferior to Open Build Service. It's a pity that RH didn't switch to it while replacing plague.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License.