# Gentoo Production Buildhoster - Sample Tutorial Instructions
# Copyright (c) 2005 Mike Green <mikey at badpenguins dot com>
# Released under the GNU GPLv2

Welcome to the sample tutorial instructions for Gentoo Production Buildhoster.
This document outlines the basic steps required to get started with build
hosting.  For a deeper understanding consult the source.

1)  Download the latest gentoo-buildhoster ebuild, generate the digest.

    # EBUILD_NAME="gentoo-buildhoster-0.4.2.ebuild"
    # mkdir -p /usr/local/portage-overlay/app-admin/gentoo-buildhoster
    # cd /usr/local/portage-overlay/app-admin/gentoo-buildhoster
    # wget http://badpenguins.com/source/gentoo-buildhoster/$EBUILD_NAME
    # ebuild $EBUILD_NAME digest

2)  Install gentoo-buildhoster

    # PORTDIR_OVERLAY="/usr/local/portage-overlay" emerge gentoo-buildhoster

3)  The default configuration sets the BUILDHOST_ROOT to:

    /var/buildhoster/buildhosts

    You will need at least enough disk space to house a portage snapshot, a
    stage1 tarball, and the buildhost itself.  If this default location does
    not work for you, edit /etc/buildhoster/buildhosters.conf and change
    BUILDHOST_ROOT.  Don't change anything else until you have completed these
    instructions and have a basic understanding of how gentoo buildhoster
    functions.

4)  Source the configuration file.  This is not normally required, it will
    allow these instructions to reference variable names instead of hard
    coded paths.

    # source /etc/buildhoster/buildhoster.conf

5)  Run buildhost --list, no buildhosts exist yet, but it will create all of
    the required directories.

    # buildhost --list

6)  Decide on the snapshot date that will be used to generate the build host.
    Generally the latest snapshot available on the gentoo mirrors is the
    previous days snapshot.  This document was updated on 2006-04-08 so the
    date used throughout this document will be 20060407.

    # cd $BUILDHOST_SNAPSHOTS
    # wget http://distfiles.gentoo.org/snapshots/portage-20060407.tar.bz2

7)  Obtain a stage tarball.  These instructions cover building from stage1,
    so we grab the latest stage1 available at the time this was written.

    # cd $BUILDHOST_STAGES
    # STAGE="stage1-x86-2006.0.tar.bz2"
    # wget http://distfiles.gentoo.org/releases/x86/2006.0/stages/$STAGE

8)  Copy over the sample configs and overlay.

    # configs="/usr/share/doc/gentoo-buildhoster*/samples/specs"
    # cp -a $configs/* $BUILDHOST_CONFIGS
    # overlay="/usr/share/doc/gentoo-buildhoster*/samples/overlays"
    # cp -a $overlay/sample-overlay $BUILDHOST_OVERLAY_CACHE

9)  Set up the spec file for the build host, using sample-stage3-p3.spec as a
    template.  The sample is already set up for a generic pentium3 build.
    The only item that probably requires alteration is the snapshot: tag.

    # cd $BUILDHOST_CONFIGS
    # <YOUR_FAVORITE_EDITOR> sample-stage3-p3.spec

10) Initialize the build host, using the snapshot and stage tarballs that were
    previously downloaded.

    # buildhost --create sample-stage3-p3

11) Convert the stage1 build host into a stage3.  The buildhost --stage3
    argument runs a customized bootstrap.sh and subsequent emerge -e system
    within the chroot.  This command will create a stage tarball when
    it completes.

    # buildhost --stage3 sample-stage3-p3

12) We now have a working stage3 snapshot that will be used to create the
    sample web server buildhost.  Get rid of the sample-stage3-p3 build
    host since it is no longer needed.

    # buildhost --unmount sample-stage3-p3
    # rm -rf $BUILDHOST_ROOT/sample-stage3-p3

13) Create the sample-web-server build host spec file.

    # cd ${BUILDHOST_CONFIGS}
	# cp sample-stage3-p3.spec sample-web-server.spec

14) Edit the build host spec file to add the sample overlay and define
    the packages that will be built within the build host.

    # <YOUR_FAVORITE_EDITOR> sample-web-server.spec

    Set/modify the following tags:
    stage: sample-stage3-p3-20060407
    features: -ccache -distcc buildpkg
    overlay: sample-overlay
    build_package: sys-kernel/poweredge-sc420
    build_package: server-configs/sampleweb-configs
    build_package: server-metapackages/metapackages-web-server

15) Generate the sample-overlay's digest files.

    # buildhost --refresh-digests

16) Create the buildhost

    # buildhost --create sample-web-server

17) Manually enter the build host and start the build.

    # buildhost sample-web-server
    # refresh-buildhost
    # exit

or

18) Optionally run the automated build.

    # buildhost --refresh sample-web-server

19) The packages will be created in:

    $BUILDHOST_PACKAGES_CACHE/sample-web-server/20060407