summaryrefslogtreecommitdiffstats
path: root/doc/installation
diff options
context:
space:
mode:
Diffstat (limited to 'doc/installation')
-rw-r--r--doc/installation/building-packages.txt228
-rw-r--r--doc/installation/distributions.txt7
-rw-r--r--doc/installation/index.txt2
-rw-r--r--doc/installation/packages.txt81
-rw-r--r--doc/installation/prerequisites.txt6
-rw-r--r--doc/installation/source.txt11
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