Deprecated documentation

This documentation is out-of-date, please refer to the latest version at: https://linux.web.cern.ch/koji/ .

Quickstart

• Get familiar with the web interface: http://koji.cern.ch/koji/ (Login use kerberos and need the cern package mozilla-prefs installed.)
• Install koji client

     yum install koji 
     

• Ask linuxsupport team for an account in Snow : https://cern.service-now.com/service-portal?id=sc_cat_item&?name=general-request-Linux&se=linux-desktop
• Mentioned in the ticket what tag do you want to work with.
• Configure your client : https://cern.service-now.com/service-portal/article.do?n=KB0005632

• Execute 'koji list-permissions --mine' and you should get as an answer "build" :

     $ koji list-permissions --mine
       build
     

• If you DO NOT use SLC5/6, Firefox needs two additional settings for Kerberos (about:config) :

       network.negotiate-auth.trusted-uris -> .cern.ch
       network.negotiate-auth.delegation-uris -> .cern.ch
       

• EXPERIMENTAL Chrome (Not supported) : you need to launch it with these arguments " --auth-negotiate-delegate-whitelist --auth-server-whitelist="*cern.ch" "
• OPTIONAL : If you want to run more than one koji you can use alias :

       alias cern-koji="koji --config=~/.koji/config-cern"
       alias fedora-koji="koji --config=~/.koji/config-fedora"
       

• BONUS : auto completion for zsh and bash users : https://github.com/rnc/brew-koji
• If you plan to use puppet: read the "Repositories" and "Workflow" section on this page.

Repositories

• All tag in koji have a corresponding repository on http://linuxsoft.cern.ch/internal/repos/
• These repositories are synced every 10 mins.
• We do not provide .repo file automatically, an example can be seen here if you follow the AI workflow (http://linuxsoft.cern.ch/internal/repos/ai6.repo).
• If your machine is puppet managed, consider reading about osrepo module.

Repositories location

• Repositories Linuxsoft : http://linuxsoft.cern.ch/internal/repos/

RPM 101

• A rpm is composed of a NAME, VERSION, RELEASE(which contains a DISTTAG)

      ksh-20120801-10.el6_5.4
      NAME=ksh
      VERSION=20120801
      RELEASE=10.el6_5.4
      DISTTAG=el6_5
      

• A rpm is build with "rpmbuild -ba". If it doesn't work on your machine it will not work in Koji. However if it works on your machine it may not work on Koji (dependencies you have installed but not documented in the spec file, afs dependency, tag not defined, etc..)
• To generate a clean buildroot koji uses "mock".
• A rpm N V R is unique in koji.
• When you release a new RPM, bump the release number and associate it with a Changelog entry in the .spec file.

Workflow

Agile Infrastructure workflow

• As agreed with the AI team, the default workflow is the following:

• We consider your machine runs puppet and use the provided repositories definition.
• The tag used in the example is ai6 but it can be yours.
• IMPORTANT If you request a new tag it is your responsibility to use best practice for your puppet module repository definition. (20/03/2014: Set a osrepo_mytag_qa_enable hiera variable. Add to your manifest the -qa repo and enable it only if hiera variable osrepo_mytag_qa_enable is enabled. Detailled doc will be available, please contact the config management team in case you have questions.)

Now we will see how to execute step 1, 3 and 5.

Build from src.rpm

NOTE: All the build operation can be executed with "--scratch" to test if your package build correctly. Koji is not a CI server.

• Add packages to your tag, as an example we use ai6 tag:

     koji add-pkg --owner=ai-team ai6-testing mypkg
     koji add-pkg --owner=ai-team ai6-qa mypkg
     koji add-pkg --owner=ai-team ai6-stable mypkg
     

  This operation is only needed once when you add a new package.

NOTE: There is no notion of group in Koji, only users. So the "--owner" can be set to your username if you do not have a specific user like "ai-team" declared in koji. If you want a user for a team let us know.

• Build your package:

    koji build ai6 mypkg-1.2-4.el6.src.rpm
    

• Your package will be shortly available in -testing.

Build from git

NOTE: All the build operation can be executed with "--scratch" to test if your package build correctly. Koji is not a CI server.

• Your repository must be configured with anonymous access inside CERN. Ensure the git repository Access is set to CERN at https://cernforge.cern.ch/git/myprojects

AI projects should contain either :

• A "sources" target that generate the needed source files. The "make sources" command should generate all your missing "SourceX:" according to the naming you did choose in the spec file.
• Or a "Makefile.koji" file. Note: PKGNAME must match the specfile Source[0,]: definition (e.g: "%{name}-%{version}")

Example:

PKGNAME=ai-tools-1.6
TARFILE=$(PKGNAME).tgz

all:
	tar cvzf $(TARFILE) --exclude-vcs --transform 's,^,$(PKGNAME)/,' *

clean:
	rm $(TARFILE)

• Add packages to your tag, as an example we use ai6 tag:

     koji add-pkg ai6-testing mypkg
     koji add-pkg ai6-qa mypkg
     koji add-pkg ai6-stable mypkg
     

  This operation is only needed once when you add a new package.

Build from gitlab.cern.ch

• Your Gitlab project must be configured with visibility set to "Internal" (i.e. all authenticated CERN users can access the project) or "Public" (i.e. all Internet users can access the project without authentication). See Gitlab documentation on visibility levels
• NB: Alternatively, you may use a project with visibility set to "Private" and explicitly grant access to user "koji support", but take into account that the source RPM built by Koji will be open to all CERN users anyway.

Example:

$ koji build ai6 git+ssh://git@gitlab.cern.ch:7999/ai-config-team/ai-tools.git#8.12-1

Note: if you run : koji build ai6 git+http://git.cern.ch/cernpub/certmgr-client#0.2.13, koji will run the following commands:

$ git clone -n git+ssh://git@gitlab.cern.ch:7999/ai-config-team/ai-tools.git /var/build/mock/ai6-build-42730-30259/root/tmp/scmroot/ai-tools
Initialized empty Git repository in /var/build/mock/ai6-build-42730-30259/root/tmp/scmroot/ai-tools/.git/
$ git reset --hard 0.2.13
HEAD is now at e3471a9 version bump for ca.pem management

Promote a package

• Tag your build to -qa:

     koji tag-build ai6-qa mypkg-1.2-4.el6
     

• Create a CRM ticket following this template with "Proposed date for production" set in a week time:

• Your package will be available in -qa in maximum 15 minutes. (a cron job runs every 5 minutes to fetch new packages)
• Wait a week and check if your ticket is not a blocker for anyone else.

• Tag it to -stable:

     koji tag-build ai6-stable mypkg-1.2-4.el6
     

• Your package will be available in -stable in maximum 15 minutes. (a cron job runs every 5 minutes to fetch new packages)

Request a new tag

* Complete this service portal form

• All tag name should be short and will have the distribution major release number in it's final name (ai5.ai6 etc..)
• If you need snapshots please request it.
• if you need your packages to be signed request it. (BETA)

Known issues

• If you have python "certifi" installed or other libraries with mingle with the certificate bundle you will need to set REQUESTS_CA_BUNDLE variable. export REQUESTS_CA_BUNDLE=/etc/ssl/certs/CERN-bundle.pem