Debian Packaging » History » Revision 22
Revision 21 (Dominic Cleal, 04/10/2015 10:25 AM) → Revision 22/35 (Dominic Cleal, 10/07/2015 07:22 AM)
h1. Debian Packaging
{{toc}}
h2. Artifacts
The following artifacts are generated from the Deb build process and form part of any release:
* foreman, including database and compute resource subpackages
* foreman-installer
* foreman-proxy
* dependencies
h2. Jenkins
Jenkins is used to automate the package builds, using the jobs:
* http://ci.theforeman.org/view/Packaging/job/packaging_build_deb_dependency (for gems)
* http://ci.theforeman.org/view/Packaging/job/packaging_build_deb_plugin (for plugins)
* http://ci.theforeman.org/view/Packaging/job/packaging_build_deb_coreproject (for core/proxy/installer)
These jobs rely on matching the branching structure of the core projects to the branching in foreman-packaging.
In addition these matrix jobs build regular 'scratch' packages from the develop HEAD
* http://ci.theforeman.org/view/Packaging/job/packaging_build_foreman_matrix
* http://ci.theforeman.org/view/Packaging/job/packaging_build_foreman-proxy_matrix
The matrix jobs only presently build the nightly packages, thus RC/Stable releases will be queued manually using the basic jobs. The configuration depends on the build you want:
h3. Scratch build parameters
h4. Want to test your own branch?
Push your packaging updates to your fork of foreman-packaging:deb/develop
Change repoowner to your GitHub account
Select project (core/proxy/installer)
Select OS ('all', or a specific target)
branch should be 'develop'
leave PR field blank
gitrelease should be ticked
The packages will be on stagingdeb.theforeman.org/<os>/<your github user>. To use in apt, add this to sources.list:
deb http://stagingdeb.theforeman.org/ os username
h4. Want to test a PR?
repoowner must be theforeman
Select project (core/proxy/installer)
Select OS ('all', or a specific target)
branch must be x.y (e.g 1.3) - this is both the branch of foreman-packaging _and_ the target component on deb.theforeman.org
set PR field to the number of the PR (e.g 113)
gitrelease must be ticked
Final packages will be pushed to stagingdeb.theforeman.org/<os>/theforeman and marked with the string "pr(#number)"
h4. Release (RC or final) build parameters
This should only be done by the release nanny.
Make necessary merges from theforeman/foreman-packaging:deb/develop to deb/<release> (e.g. '1.3')
repoowner must be theforeman
Select project (core/proxy/installer)
Select OS ('all', or a specific target)
branch must be x.y (e.g 1.3) - this is both the branch of foreman-packaging _and_ the target component on deb.theforeman.org
leave PR field blank
gitrelease must be unticked
Final packages will be pushed to deb.theforeman.org/<os>/<branch>
h3. Nightly build parameters
These are triggered normally by other jobs in Jenkins, e.g. the test_develop job triggers the Deb matrix job with the following parameters.
repoowner will be theforeman
project is determined by the upstream job (eg test_develop will trigger project=foreman)
branch will be develop
pr be blank
gitrelease will be ticked
h2. Tooling
h3. Pbuilder
"Pbuilder":http://www.netfort.gr.jp/~dancer/software/pbuilder-doc/pbuilder-doc.html is the system used internally by jenkins to build the packages for each of the architectures. It should just work, but if there are problems, you can look at the pbuilder module in foreman-infra for more detail.
h3. Jenkins
Jenkins is used to prepare the package sources, and the upstream sources, execute the appropriate pbuilder OS environment, and then upload the resulting packages to the appropriate deb repo.
h3. Freight
Freight is used to add individual debs to the overall repo. The following actions are performed:
* Packages are rsync'ed to (staging)deb.theforeman.org from the Jenkins package build
* @freight-add <debs> apt/<os>/<repo>@ is used to stage the debs for adding
* @freight-cache apt/<os>@ is used to rebuild the repo and publish it
Key locations:
* /home/freight(stage) is the home directory of the user managing the repo, contains freight.conf
* /var/www/freight(stage) is the freight library, where new packages are staged to with freight-add
* /var/www/vhosts/(stage)deb/htdocs/ is the freight cache, the public viewable archive
There are cron jobs which clean out old nightly, and scratch debs after 7 days.
This should all happen automatically, this information is only provided for background. See foreman-infra/puppet/modules/freight for more code.
To delete packages, remove them from the freight library, from the pool in the freight cache and then run the @freight-cache@ command to regenerate the archive.
h2. Project sources
h3. foreman
Foreman{,proxy,installer} is built from the packaging constructs in the foreman-packaging repo:
* https://github.com/theforeman/foreman-packaging/tree/deb/develop (or 1.2/1.3/etc)
This repo is pulled in by Jenkins, thefore build preparation consists of appropriately updating this repo before queueing the Jenkins jobs.
h4. Initial tests
The nightly repo tracks the develop branch. At the point when a release candidate is forked, nightly will most likely be at the same commit, and will already be built (as it is triggered by a commit to develop). Thus, if the nightly packages work, one can conclude the packaging constructs in deb/nightly are probably sane. Minimal testing using a scratch build from your own repo is recommended, as above.
h4. Branching for release Release candidate
The following steps are used to set step up a new release version repo candidate build from nightly. nightly
* Cherry-pick appropriate commits from deb/develop into deb/<version> (e.g. deb/1.3)
* Update the UPSTREAM variable in <package>/build_vars.sh to point to correct git-tag for the release (e.g. UPSTREAM=1.3.0-RC1) (TODO: make this a jenkins option like the rpms?)
* Create a new dir for the new release (e.g. 1.3) and add an "rc" symlink to it (eg staged/apt/<os>/1.3 and staged/apt/<os>/rc -> 1.3)
* ** Something like this should copy all the current deps from nightly:
** *** Log in to deb.theforeman.org
** *** sudo -u freight -s /bin/bash
** *** cd /var/www/freight/apt/wheezy && cp -r nightly 1.3 1.4 && ln -snf 1.4 rc && rm -f 1.3/*9999* rc/*9999*
** *** delete older versions of packages from rc/* (eg where you have ruby-clamp_0.6.2-1_all.deb & ruby-clamp_0.6.2-2_all.deb, delete 0.6.2-1)
** *** cd /var/www/vhosts/deb/htdocs/pool/ && rm -rf wheezy/rc # clean up the web cache too
* ** Repeat for the other debian OSs and the plugins repo
* ** Use freight-cache to create new rc repo:
** *** freight cache -v -c ~/freight.conf
* ** It's also necessary to copy the current build deps to the staging repo. Once the above is done, you can use:
** *** sudo -u freightstage -s /bin/bash
** *** find /var/www/freight/apt/wheezy/1.3/ /var/www/freight/apt/wheezy/1.7/ -iname "*deb" -exec freight-add -v -c /home/freightstage/freight.conf {} apt/wheezy/theforeman-1.3 apt/wheezy/theforeman-1.7 \;
** *** repeat for each OS
** *** freight cache -v -c ~/freight.conf
* Update the changelog with a block announcing the release candidate, e.g:
<pre>
foreman (1.3.0~rc1-1) stable; urgency=low
* Release 1.3.0 RC1
-- Greg Sutcliffe <greg.sutcliffe@gmail.com> Fri, 12 Sep 2013 16:31:00 +0100
</pre>
** Note the Debian changelog is _extremely_ sensitive to format and syntax. If in doubt, do this on a debian box and use the "dch -i" tool to add the entry
** Use <release-in-three-parts>~rc<rc-version>-1<packaging-release> as the release to ensure the first stable release can use "-1"
* PR / Commit the git changes to foreman-packaging:deb/<version>
* Queue the Jenkins jobs!
* Test the resulting packages
h4. Stable release
The stable release is almost identical to the rc release, with good reason ;)
* Foreman-packaging/deb/1.3 should already be up-to-date
* Update the UPSTREAM variable in <package>/build_vars.sh to point to correct git-tag for the release (e.g. UPSTREAM=1.3.0)
* Add any new dependencies from rc to stable (most should already be present, as RCs and Stable release share a numbered repo)
** Same process on server2, but also update the symlinks for "stable" to point to the new release, and delete the rc symlinks
* Update the changelog with a block announcing the release, e.g:
<pre>
foreman (1.3.0-1) stable; urgency=low
(as above for the rest)
</pre>
* PR / Commit the git changes to foreman-packaging:deb/1.3
* Queue the Jenkins jobs!
* Test the resulting packages
Foreman-packaging/deb/<version> remains as a branch for point-releases on old versions
h3. foreman-proxy
The exact same process above is used to release the proxy.
h3. foreman-installer
The exact same process above is used to release the proxy.
h3. Dependencies
Gem dependencies can be built from the same foreman-packaging/<version|develop> repo as the core packages, using the 'packaging_build_deb_dependency' job. Currently only gems can be built, using a modified gem2deb command which replaces the auto-generated debian/ dir with the one from our git repo during the build.
TODO(13/9/13): Non-gem dependencies cannot currently be built automatically, this will be fixed at some point.
If you need to manually build
Foreman's Debian dependencies should all be present in the nightly repo in order to make the nightly builds work. Work is underway to store the appropriate packaging constructs in the foreman-packaging repo, such that they can be rebuilt if needed. The packages are built using pbuilder manually. Rough notes on performing this build are:
* Log in to server9 (the debian slave node)
* Clone foreman-packaging:deb/develop
* cd to the appropriate package and prepare the sources
* run pdebuild-<os_arch> (eg. pdebuild-squeeze32) to generate a package for that OS/Arch
* Upload to server2 and use freight to add to the repo
h3. Plugins
Gem dependencies can be built from the same foreman-packaging/<version|develop> repo as the core packages, using the 'packaging_build_deb_plugin' job. This uses sources from the named user and packaging branch, and simply creates a bundler.d fine to be installed into the core Foreman package. It accepts a gitrelease flag if you wish to test changes
TODO: Document this properly.
h2. Nightly Builds
Nightly builds are fully automated. Next time they break I'll document what I did to fix them. Full automation is possible because of the fact that the Debian packages use gem vendoring to ship a cache of prebuilt gems to the user; thus, they are far less susceptible to changes in the Gemfile (downside: they'll never be accepted upstream)
Work has begun to start building the foreman packages using proper system gems, see http://etherpad-domcleal.rhcloud.com/p/debian-packaging for how it's going. Currently we build the installer (based on kafo) using proper system gems. Foreman itself is targeted for 1.4