elmer / crowbar Goto Github PK

This file documents how to build the Crowbar installation DVD image.

Prerequisites:
  * An unfiltered Internet connection and a decent amount of bandwidth.
    The first time you try to build Crowbar it will need to download
    all the packages that it will need to stage Crowbar onto an OS install
    DVD.
  * bash version 4 or higher
    build_crowbar.sh uses associative arrays, which bash got in version 4.
  * mkisofs
    The end product of the build script is an ISO image that will be used
    to bootstrap the Crowbar admin node. 
  * debootstrap (if staging on to Ubuntu)
    The build process needs to download all the .debs and gems that 
    Crowbar requires, and we don't want to inadvertently mess up the build
    machine when we do that.  All extra packages are downloaded into a
    chrooted minimal Ubuntu intall, and we use debootstrap to enable that.
  * Sudo to root privileges for the following commands:
    * /bin/mount, /bin/umount
      We have to be able to mount and umount the Ubuntu .iso image, as well as
      a tmpfs for debootstrap, and we have to be able to bind mount 
      /dev, /dev/pts, /proc, and /sys into the debootstrap chroot environment.
    * /usr/sbin/debootstrap
      debootstrap requires root privileges to run.
    * /bin/cp
      We need to copy things into and out of the debootstrap environment to
      ensure it downloads and caches the right packages.
    * /usr/sbin/chroot
      All our package caching is done in a chroot environment, and chroot
      requires root permissions to run.

      If you want to allow build_crowbar to run the above commands as root
      without having to enter a password each time, the build_crowbar.sh
      includes a sample line you can fix up and add to /etc/sudoers.
  * A working Sledgehammer tftpboot image.
    Sledgehammer is a minimal CentOS 5.6 pxe bootable image that we use
    to perform hardware discovery and configuration for devices that do not
    have low-level management tools for Ubuntu. You can find information on 
    how to build Sledgehamemr by reading its HOWTO.Non.Redhat file.  We do 
    not do fully automated builds of Sledgehammer due to a lack of a CentOS
    equivalent of debootstrap.

Command Line Parameters:
  * The first command line parameter is the OS you want to 
    stage Crowbar on to.  Crowbar currently understands how to stage on to 
    ubuntu-10.10 and redhat-5.6
  * --update-cache
    This parameter forces the build to try and update the build cache again.  
    Use this parameter if you want to pull in updates from the upstream repositories
    that Crowbar pulls packages from.
  * --merge|-m
    Any arguments after this that do not start with a hyphen are interpreted as
    branches in the git repository that you want to merge along with the current
    branch into a throwaway branch before staging Crowbar on to the build .iso.
    If you are working on developing a barclamp or have changes in other branches
    that you want to test out, this is the option for you. If your build cache is
    also a git repository, it will try to merge identically named branches in that
    repository as well -- this is a good way of testing new packages before 
    signing off on them. After the build is finished, the build script will delete
    any throwaway branches it created, leaving the repositories in the same state
    they started in. 

Usage:
  * Run build_crowbar.sh from the Crowbar git repository.  
    The first time it is run, it will download and cache all the files it 
    needs to stage Crowbar on to the OS installation DVD, build an OS install
    ISO with Crowbar staged on to it, save the generated .ISO to the current 
    working directory, and print out a message saying where it saved the image.
    On subsequent runs it will run with the files it cached from the first
    run, unless update-cache is passed as a parameter to the script.

Customization:
  
   build_crowbar.sh has several different parameters you can tune, either from
   $HOME/.build-crowbar.conf (for developer use), or from build-crowbar.conf
   in the current directory (for automated builds).

   Here are the parameters you can change through the above configuration files:
   * DEBUG
     If DEBUG is set to anything, build_crowbar will run in debug mode, and will
     print a transcript of everything it is doing to standard error.
   * CACHE_DIR
     This is the default location where build_crowbar.sh will keep the files
     it caches, along with the temporary directories used to mount the
     ISO image, the debootstrap chroot, and the directory we perform the build
     in.  It defaults to $HOME/.crowbar-build-cache.
   * ISO_LIBRARY
     This is the default location where the Ubuntu .iso is stored. It defaults 
     to $CACHE_DIR/iso
   * ISO_DEST
     This is the location that we will save the Crowbar install image to.
     It defaults to the current directory.
   * IMAGE_DIR
     This is the location that we will mount isos in.  
     It defaults to $CACHE_DIR/image
   * SLEDGEHAMMER_PXE_DIR
     This points to the location we expect to find the unpacked Sledgehammer
     PXE boot archive.  It defaults to $CACHE_DIR/tftpboot
   * VERSION
     The default version of Crowbar.  Defaults to dev.
   * BUILT_ISO
     The name of the ISO that build_crowbar.sh generates.
     Defaults to crowbar-$VERSION.iso
   * CROWBAR_DIR
     The directory that the Crowbar source is cheched out to.
     Defaults to the directory that build_crowbar.sh is in.
   * SLEDGEHAMMER_DIR
     The directory that the Sledgehammer source is checked out to.
     Defaults to $CROWBAR_DIR/../sledgehammer
   * VCS_CLEAN_CMD
     This is the command that build_crowbar.sh will run to clean the tree before
     staging the Crowbar build.  
     Defaults to 'git clean -f -x -d'

The build_crowbar.sh script is heavily commented, please refer to it for more 
detailed information.