diff options
Diffstat (limited to 'doc/installation')
| -rw-r--r-- | doc/installation/building-packages.txt | 228 | ||||
| -rw-r--r-- | doc/installation/distributions.txt | 7 | ||||
| -rw-r--r-- | doc/installation/index.txt | 2 | ||||
| -rw-r--r-- | doc/installation/packages.txt | 81 | ||||
| -rw-r--r-- | doc/installation/prerequisites.txt | 6 | ||||
| -rw-r--r-- | doc/installation/source.txt | 11 |
6 files changed, 245 insertions, 90 deletions
diff --git a/doc/installation/building-packages.txt b/doc/installation/building-packages.txt new file mode 100644 index 000000000..b3b775869 --- /dev/null +++ b/doc/installation/building-packages.txt @@ -0,0 +1,228 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + +.. _installation-building-packages: + +============================= +Building packages from source +============================= + +Building RPMs +============= + +Building from a tarball +----------------------- + +* Create a directory structure for rpmbuild:: + + rpmdev-setuptree + +* Copy the tarball to ``~/rpmbuild/SOURCES/`` +* Extract another copy of it somewhere else (eg: ``/tmp``) and retrieve + the ``misc/bcfg2.spec`` file +* Run the following:: + + rpmbuild -ba bcfg2.spec + +* The resulting RPMs will be in ``~/rpmbuild/RPMS/`` and SRPMs + in ``~/rpmbuild/SRPMS/``. + +Building Debian packages +======================== + +The Bcfg2 project provides a ``debian`` subdirectory with the project's +source that enables users to create their own Debian/Ubuntu compatible +packages (`.deb` files). + +Build deps +---------- + +If the distribution you are building on already has packaged bcfg2 +(even an older version), the following command will likely install the +necessary build dependencies:: + + apt-get build-dep bcfg2 bcfg2-server + +Install source code +------------------- + +Depending on which version of bcfg2 you want build, you can obtain the +source code from the Download_ page or from the project's git repository. +To create a local anonymous working copy of the latest version of the +bcfg2 source code, use a command like the following:: + + git clone git://git.mcs.anl.gov/bcfg2.git + +Update the changelog +-------------------- + +The next step is to update the ``debian/changelog`` file with an +appropriate package version string. Debian packages contain a version +that is extracted from the latest entry in this file. An appropriate +version will help you distinguish your locally built package from one +provided by your distribution. It also helps the packaging system know +when a newer version of the package is available to install. + +It is possible to skip this step, but the packages you build will have +the same version as the source distribution and will be easy to confuse +with other similarly named (but maybe not equivalent) packages. + +The basic format of the package version string to use is this:: + + <UPSTREAM VER>~<UPSTREAM PRE-VER>+<GIT-ID>-0.1+<LOCAL VER> + +.. note:: + The '+', and '-' characters have significance in determining when + one package is newer than another. The following format is believed + to do the right thing in all common situations. + +The components of the package version string are explained below: + +.. glossary:: + + <UPSTREAM VER> + This is the version of the Bcfg source code you are working + from. It will likely be something like `0.9.6` or `1.0`. + + <UPSTREAM PRE-VER> + If you are using a published pre-release of Bcfg2, it will have + a name like `pre1` or `rc1`. Use that string here, otherwise + drop this component from the package version string. + + +<GIT-ID> + If you are building from a local working copy of the git + repository, it is useful to include the revision in the package + version. If you are building from a downloaded copy of the source, + drop this component (including the preceding plus-sign (`+`) + from the package version string. + + +<LOCAL VER> + This is a locally relevant name like your last name or your + domain name, plus the digit `1`. For example, if your family + name is ''Smith'', you could use `smith1`. If you work for + ''Example Inc'', you could use `example1`. + +Here are some examples: + +* If you are building packages for revision 6c681bd from git, and the + latest published version is 1.2.0rc1, the version string should be + `1.2.0rc1+6c681bd-0.1+example1`. +* If you are building packages for the published 1.0 rc1 version, the + version string should be `1.0rc1-0.1+example1`. +* If you are building packages for the published 1.0 version, the version + string should be `1.0-0.1+example1`. + +If you are working on a git working copy of 1.0 pre5 and have the +``devscripts`` package installed, the following command is a convenient +way to create a well formatted changelog entry:: + + REV=$(git log --oneline | head -n 1 | cut -d' ' -f1) + debchange --force-bad-version --preserve --newversion "1.0~pre5+${REV}-0.1+example1" git revision $REV + +Building the package +-------------------- + +With the preliminaries out of the way, building the package is simple.:: + + cd .. # Change into the top level of the source directory + fakeroot dpkg-buildpackage -uc -us + +The freshly built packages will be deposited in the parent of the +current directory (``..``). Examine the output of ``dpkg-buildpackage`` +for details. + +External build systems +---------------------- + +This section describes how to build bcfg2 and deps via external build +systems (Currently only a PPA). Some other possibilities are: + + * #651 Look into project-builder to make more native-system bcfg2 packages available + * http://en.opensuse.org/Build_Service/Deb_builds + +Launchpad PPA +^^^^^^^^^^^^^ + +https://launchpad.net/~bcfg2 + +To upload to the PPA you need to be on the active member list of `Bcfg2 +in Launchpad`_. + +Note that **after each successful upload**, you should wait until the PPA +is built, and then **install it locally** using ``sudo aptitude update; +sudo aptitude install (packagename)`` so the next build doesn't fail on +your local machine. If you don't want to wait for a PPA binary build to +complete, you can "apt-get source (packagename)" and do a local build +before the PPA build is done. + +setup gpg-agent +""""""""""""""" + +Setting up gpg-agent and pinentry prevents you from having to type your +passphrase repeatedly.:: + + sudo aptitude install gnupg-agent pinentry-gtk2 pinentry-curses + # replace 0xAA95C349 with your GPG Key ID + export GPGKEY=0xAA95C349 + killall -q gpg-agent + eval $(gpg-agent --daemon) + +setup debuild +""""""""""""" + +Tell dpkg-buildpackage who you are, for example:: + + export DEBEMAIL="dclark@pobox.com" + export DEBFULLNAME="Daniel Joseph Barnhart Clark" + +upload bcfg2 to ppa +""""""""""""""""""" + +A ``dists`` file contains a space-separated list of all distributions +you want to build PPA packages for. + +.. code-block:: sh + + #!/bin/sh + + . ./dists + + # Replace 0xAA95C349 with your GnuPG Key ID + export GPGKEY=0xAA95C349 + + sudo apt-get build-dep bcfg2 bcfg2-server + sudo aptitude install git + + VERSION=1.3.2-1 + if [ ! -d testing ]; then + mkdir testing + fi + DATE=$(date +%F-%H%M) + ppa="testing" # "testing" or "ppa" (for stable) + + # download source + cd testing + git clone git://git.mcs.anl.gov/bcfg2 + cd bcfg2 + GITID=$(git log --oneline | head -n 1 | cut -d' ' -f1) + cp debian/changelog ../changelog.orig + + for dist in $DISTS + do + cp ../changelog.orig debian/changelog + (cd debian && dch --distribution ${dist} \ + --force-bad-version \ + --preserve \ + --force-distribution \ + --newversion "${VERSION}~${ppa}~${dist}${DATE}+${GITID}" \ + "bcfg2 backport for ${dist} release ${VERSION} git commit ${GITID}") + debuild --no-tgz-check -rfakeroot -I -S -k${GPGKEY} + done + + for dist in $DISTS + do + dput ppa:bcfg2/${dist}testing ../bcfg2_${VERSION}~${ppa}~${dist}${DATE}+${GITID}_source.changes + done + +.. _Download: http://bcfg2.org/download/ +.. _Bcfg2 in Launchpad: https://launchpad.net/~bcfg2 diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt index 9db111682..306439485 100644 --- a/doc/installation/distributions.txt +++ b/doc/installation/distributions.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _distributions: @@ -103,10 +104,12 @@ section will try and meet the dependencies using packages from EPEL_ [#f1]_. The *el5* and the *el6* package should be compatible with `CentOS`_ 5.x/6.x and `Scientific Linux`_. -EPEL_ for 5.x :: +EPEL_ for 5.x:: + [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm -EPEL_ for 6.x :: +EPEL_ for 6.x:: + [root@centos ~]# rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm Install the bcfg2-server and bcfg2 RPMs:: diff --git a/doc/installation/index.txt b/doc/installation/index.txt index 9f04d4b52..9bcf8be15 100644 --- a/doc/installation/index.txt +++ b/doc/installation/index.txt @@ -19,5 +19,5 @@ needs to be installed on any machine you plan to manage by Bcfg2. prerequisites source - packages + building-packages distributions diff --git a/doc/installation/packages.txt b/doc/installation/packages.txt deleted file mode 100644 index b23a870cf..000000000 --- a/doc/installation/packages.txt +++ /dev/null @@ -1,81 +0,0 @@ -.. -*- mode: rst -*- - -.. _packages: - -.. _CentOS: http://www.centos.org/ -.. _Red Hat/RHEL: http://www.redhat.com/rhel/ -.. _Scientific Linux: http://www.scientificlinux.org/ -.. _EPEL: http://fedoraproject.org/wiki/EPEL -.. _RPMForge: https://rpmrepo.org/RPMforge - - -Building RPM packages from source -================================= - -The Bcfg2 distribution contains two different spec files. - -Building from Tarball ---------------------- - -* Copy the tarball to ``/usr/src/packages/SOURCES/`` -* Extract another copy of it somewhere else (eg: ``/tmp``) and retrieve - the ``misc/bcfg2.spec`` file -* Run :: - - rpmbuild -ba bcfg2.spec - -* The resulting RPMs will be in ``/usr/src/packages/RPMS/`` and SRPMs - in ``/usr/src/packages/SRPMS`` - -Building from an GIT Checkout ------------------------------ - -* Change to the ``redhat/`` directory in the working copy -* Run :: - - make - -* The resulting RPMs will be in ``/usr/src/redhat/RPMS/`` and SRPMs - in ``/usr/src/redhat/SRPMS`` and will have the SVN revision appended - -Building RPM packages with ``rpmbuild`` ---------------------------------------- - -While you can go about building all these things from source, this -how to will try and meet the dependencies using packages from EPEL_. -The *el5* and the *el6* package should be compatible with CentOS 5.x. - -* Installation of the EPEL_ repository package :: - - [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-6.noarch.rpm - -* Now you can install the rest of the prerequisites :: - - [root@centos ~]# yum install python-genshi python-cheetah python-lxml - -* After installing git, check out the master branch :: - - [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git - -* Install the ``fedora-packager`` package :: - - [root@centos ~]# yum install fedora-packager - -* A directory structure for the RPM build process has to be established. :: - - [you@centos ~]$ rpmdev-setuptree - -* Change to the *redhat* directory of the checked out Bcfg2 source:: - - [you@centos ~]$ cd bcfg2/redhat/ - -* In the particular directory is a ``Makefile`` which will do the job of - building the RPM packages. You can do this as root, but it's not - recommended:: - - [you@centos redhat]$ make - -* Now the new RPM package can be installed. Please adjust the path to - your RPM package :: - - [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index e3434edd3..4121ff20a 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -30,6 +30,8 @@ Bcfg2 Client | debsums (if APT tool | Any | | | driver is used) | | | +----------------------------+------------------------+--------------------------------+ +| python-setuptools | Any | | ++----------------------------+------------------------+--------------------------------+ .. [#f1] python 2.5 and later works with elementtree. @@ -56,6 +58,8 @@ Bcfg2 Server +-------------------------------+----------+--------------------------------+ | python-ssl (note | Any | python, backported ssl module | +-------------------------------+----------+--------------------------------+ +| python-setuptools | Any | | ++-------------------------------+----------+--------------------------------+ Bcfg2 Reporting --------------- @@ -68,7 +72,7 @@ reporting, such as Apache + mod_wsgi or nginx. +===============================+==========+================================+ | django | 1.2.0+ | | +-------------------------------+----------+--------------------------------+ -| south | 0.7.0+ | | +| south | 0.7.5+ | | +-------------------------------+----------+--------------------------------+ Bcfg2 Reporting diff --git a/doc/installation/source.txt b/doc/installation/source.txt index 1406a5ceb..9bf023fbc 100644 --- a/doc/installation/source.txt +++ b/doc/installation/source.txt @@ -1,8 +1,9 @@ .. -*- mode: rst -*- +.. vim: ft=rst -.. _GPG1: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E -.. _GPG2: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B -.. _Download: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download +.. _7F7D197E: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E +.. _A88FFF4B: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B +.. _Download: http://bcfg2.org/download/ .. _source: @@ -17,8 +18,8 @@ Tarball The Bcfg2 source tarball can be grabbed from the `Download`_ page. -All tarballs are signed with GPG keys `7F7D197E <GPG1>`_ or `A88FFF4B -<GPG2>`_. You can verify your download by importing the keys and running :: +All tarballs are signed with GPG keys `7F7D197E`_ or `A88FFF4B`_. You +can verify your download by importing the keys and running :: gpg --recv-keys 0x75bf2c177f7d197e 0x80B8492FA88FFF4B gpg --verify bcfg2-<version>.tar.gz.gpg bcfg2-<version>.tar.gz |