Initial version of web site

Site design and layout contributed by Ryan Lerch <[email protected]>.

.gitattributes

@@ -0,0 +1,2 @@
+*.txt   whitespace=-trailing-space
+*.html  whitespace=-trailing-space

.gitignore

@@ -0,0 +1,21 @@
+/*.html
+/guide/
+/in-a-box/*.html
+/man/.buildinfo
+/man/.doctrees/
+/man/_static/
+/man/_sources/
+/man/*.html
+/man/objects.inv
+/man/searchindex.js
+/releases.mk
+/releases/
+/schema/
+/server-api/.buildinfo
+/server-api/.doctrees/
+/server-api/_modules/
+/server-api/_sources/
+/server-api/_static/
+/server-api/*.html
+/server-api/objects.inv
+/server-api/searchindex.js

COPYING.txt

@@ -0,0 +1,16 @@
+% Copyright and licensing
+
+Except as noted below, all documentation on this web site is made available
+under the [Creative Commons Attribution-ShareAlike 3.0
+license](http://creativecommons.org/licenses/by-sa/3.0/legalcode). Code is made
+available under the [GNU General Public License
+version 2](http://www.gnu.org/licenses/gpl-2.0.html).
+
+Background images are from Subtle Patterns ([Fabric
+(Plaid)](http://subtlepatterns.com/?p=939) and [Rubber
+Grip](http://subtlepatterns.com/?p=573)). They are copyright Atle Mo, used
+under the Creative Commons Attribution 3.0 license.
+
+Icons are from the
+[Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library)
+and are in the public domain.

Makefile

@@ -0,0 +1,89 @@
+
+BEAKER ?= ../beaker
+SPHINXBUILD = $(shell sh -c 'command -v sphinx-1.0-build sphinx-build')
+SPHINXBUILDOPTS = -W
+SHOCCO=$(HOME)/work/shocco/shocco # XXX fix this
+
+ARTICLES = COPYING.html dev-guide.html cobbler-migration.html
+
+include releases.mk
+OLD_TARBALLS = \
+    releases/beaker-0.6.16.tar.bz2 \
+    releases/beaker-0.6.1.tar.gz \
+    releases/beaker-0.6.1.tar.bz2 \
+    releases/beaker-0.5.7.tar.bz2 \
+    releases/beaker-0.4.75.tar.bz2 \
+    releases/beaker-0.4.3.tar.bz2 \
+    releases/beaker-0.4.tar.bz2
+
+.PHONY: all
+all: guide server-api man \
+     schema/beaker-job.rng \
+     releases/SHA1SUM releases/index.html $(DOWNLOADS) \
+     in-a-box/beaker.ks.html \
+     in-a-box/beaker-setup.html \
+     in-a-box/beaker-distros.html \
+     in-a-box/beaker-virt.html \
+     $(ARTICLES)
+
+guide::
+	# publican doesn't let us specify source or dest dirs, grumble
+	( cd $(BEAKER)/pub_doc/Beaker_Guide && \
+	  publican build --publish --common_content=$(shell pwd)/publican-common --formats=html --langs=en-US ) && \
+	rm -rf $@ && \
+	cp -r $(BEAKER)/pub_doc/Beaker_Guide/publish/en-US/Beaker/0/html/Deployment_Guide $@
+
+# This __requires__ insanity is needed in Fedora if multiple versions of CherryPy are installed.
+server-api::
+	env BEAKER=$(abspath $(BEAKER)) PYTHONPATH=$(BEAKER)/Common:$(BEAKER)/Server \
+	python -c '__requires__ = ["TurboGears"]; import pkg_resources; execfile("$(SPHINXBUILD)")' \
+	$(SPHINXBUILDOPTS) -c $@ -b html $(BEAKER)/Server/apidoc/ $@/
+
+man::
+	env BEAKER=$(abspath $(BEAKER)) PYTHONPATH=$(BEAKER)/Common:$(BEAKER)/Client/src \
+	$(SPHINXBUILD) $(SPHINXBUILDOPTS) -c $@ -b html $(BEAKER)/Client/doc/ $@/
+
+schema/beaker-job.rng: $(BEAKER)/Common/bkr/common/schema/beaker-job.rng
+	mkdir -p $(dir $@)
+	cp -p $< $@
+
+releases.mk: $(BEAKER)/beaker.spec generate-releases-mk.py changelog.py
+	./generate-releases-mk.py <$< >$@
+
+releases/index.html: $(BEAKER)/beaker.spec releases/SHA1SUM generate-releases-index.py changelog.py
+	mkdir -p $(dir $@)
+	./generate-releases-index.py <$< >$@
+
+releases/%.tar.gz:
+	mkdir -p $(dir $@)
+	( cd $(BEAKER) && flock /tmp/tito tito build --tgz --tag=$*-1 ) && cp /tmp/tito/$*.tar.gz $@
+
+releases/%.tar.xz: releases/%.tar.gz
+	mkdir -p $(dir $@)
+	gunzip -c $< | xz >$@
+
+releases/%.patch:
+	mkdir -p $(dir $@)
+	( cd $(BEAKER) && flock /tmp/tito tito build --tgz --tag=$* ) && cp /tmp/tito/$*.patch $@
+
+releases/SHA1SUM: $(DOWNLOADS) releases.mk
+	mkdir -p $(dir $@)
+	( cd $(dir $@) && ls -rv $(notdir $(DOWNLOADS)) $(notdir $(OLD_TARBALLS)) | xargs sha1sum ) >$@
+
+in-a-box/%.html: in-a-box/%
+	$(SHOCCO) $< >$@
+
+%.html: %.txt pandoc-before-body.html pandoc-after-body.html
+	pandoc -f markdown -t html -5 --standalone --section-divs --smart --css=style.css \
+	    --include-in-header=pandoc-header.html \
+	    --include-before-body=pandoc-before-body.html \
+	    --include-after-body=pandoc-after-body.html \
+	    <$< >$@
+
+.PHONY: check
+check:
+# ideas: spell check everything, validate HTML, check for broken links, check yum repo deps
+
+.PHONY: publish
+publish:
+	env BEAKER="$(abspath $(BEAKER))" ./publish.sh published

README

@@ -0,0 +1,52 @@
+
+This is the beaker-project.org web site.
+
+To make changes, edit the relevant file and then run `make` to update
+the generated files. You must have a clean, up-to-date checkout of the
+master branch of Beaker's git for the documentation to be built. The
+Makefile assumes Beaker can be found in ../beaker; if not, you must pass
+the path in the BEAKER variable, e.g. `make BEAKER=/home/dan/beaker`.
+
+Note that many parts of this web site are generated from elsewhere:
+
+    * Some .html pages are generated from the corresponding .txt file in
+      Markdown using Pandoc.
+    * Some documentation is built using Sphinx from docstrings extracted
+      from Beaker code.
+    * Some documentation is built using Publican from DocBook sources
+      included in Beaker.
+    * Some shell scripts have a pretty documented version which is
+      generated by shocco.
+
+
+Publishing the web site
+-----------------------
+
+These instructions are only relevant to Beaker developers who have
+access to publish to beaker-project.org.
+
+Only publish changes that are already on the master branch. Make sure
+your master branch is up to date:
+
+    git checkout master
+    git pull
+
+Also make sure your 'published' branch is up to date. This is a special
+branch for tracking the published version of the web site (including all
+generated artefacts):
+
+    git fetch beaker-project.org:/srv/www/beaker-project.org/git/ master:published
+
+Build your changes:
+
+    make publish
+
+Now the 'published' branch has been updated. You may want to push it to
+http://stage.beaker-project.org/ first, to make sure everything looks
+okay:
+
+    git push beaker-project.org:/srv/www/stage.beaker-project.org/git/ published:master
+
+Once you're happy with it, push it live:
+
+    git push beaker-project.org:/srv/www/beaker-project.org/git/ published:master

beaker-client-Fedora.repo

@@ -0,0 +1,5 @@
+[beaker-client]
+name=Beaker Client - Fedora$releasever
+baseurl=http://beaker-project.org/yum/client/Fedora$releasever/
+enabled=1
+gpgcheck=0

beaker-client-RedHatEnterpriseLinux.repo

@@ -0,0 +1,5 @@
+[beaker-client]
+name=Beaker Client - RedHatEnterpriseLinux$releasever
+baseurl=http://beaker-project.org/yum/client/RedHatEnterpriseLinux$releasever/
+enabled=1
+gpgcheck=0

beaker-server-RedHatEnterpriseLinux.repo

@@ -0,0 +1,5 @@
+[beaker-server]
+name=Beaker Server - RedHatEnterpriseLinux$releasever
+baseurl=http://beaker-project.org/yum/server/RedHatEnterpriseLinux$releasever/
+enabled=1
+gpgcheck=0

changelog.py

@@ -0,0 +1,48 @@
+
+import re
+import datetime
+
+BAD_VER_RELS = [
+    # divergent, so they don't produce a usable patch series
+    '0.8.0-24.1',
+    '0.8.1-5.1',
+    '0.8.1-5.2',
+    # pre-releases, not real releases that we want people to use
+    '0.8.99-1',
+    '0.8.99-2',
+    '0.8.99-3',
+]
+
+# Is there any better parser we could use here??? e.g. from rpm
+
+class Release(object):
+
+    def __init__(self, version, release, date, changes):
+        self.version = version
+        self.release = release
+        self.date = date
+        self.changes = changes
+
+    @property
+    def downloads(self):
+        if self.release != '-1':
+            return ['beaker-%s%s.patch' % (self.version, self.release)]
+        else:
+            return ['beaker-%s.tar.gz' % self.version,
+                    'beaker-%s.tar.xz' % self.version]
+
+def parse(spec):
+    _, _, changelog = spec.partition('\n%changelog\n')
+    releases = re.split(r'(?m)(^\*.*$)', changelog)
+    releases.pop(0) # empty string
+    while releases:
+        date, releaser, ver, rel = re.match(
+                r'\* \w{3} (\w{3} \d+ \d{4}) (.*?) ([\d.]+)(-.*)?',
+                releases.pop(0)).groups()
+        changes = [c.replace('%%', '%') for c in re.split(r'(?m)^- ', releases.pop(0)) if c.split()]
+        if ver + rel in BAD_VER_RELS:
+            continue
+        date = datetime.datetime.strptime(date, '%b %d %Y').date()
+        yield Release(ver, rel, date, changes)
+        if (ver, rel) == ('0.6.2', '-1'):
+            break # don't bother with the really old stuff

cobbler-migration.txt

@@ -0,0 +1,121 @@
+% Cobbler migration
+
+As of version 0.9, Beaker no longer relies on Cobbler for provisioning systems.
+A new lab controller daemon, `beaker-provision`, executes power commands and
+manages the TFTP root. Kickstarts are generated by and served from the Beaker
+server.
+
+Within Beaker itself, complete compatibility has been maintained and the change
+should be largely invisible. In particular, kickstart metadata for systems and
+recipes will behave the same as in previous releases.
+
+However, if your site is using any Cobbler functionality directly you may need
+to take steps to migrate the configuration to Beaker.
+
+
+Install options for Cobbler distros
+-----------------------------------
+
+If you have set kickstart metadata, kernel options, or post-install kernel
+options for any distros in Cobbler (for example using `cobbler distro edit`)
+you will need to find the equivalent distro tree in Beaker's web UI and set the
+options there. The format and meaning of the install options in Beaker are the
+same as in Cobbler.
+
+
+Power scripts
+-------------
+
+When executing power commands, Beaker uses shell scripts which are based on
+Cobbler's power templates which are installed in `/etc/cobbler/power`. If you
+have customised any of Cobbler's power templates you may need to add a custom
+Beaker power script with the same modifications. Refer to [Customizing Power
+Commands](guide/Administration-Customizing_Power_Commands.html) in the Beaker
+Guide.
+
+Note that Beaker uses shell scripts rather than Cheetah templates for power
+commands, even though the shell scripts look very similar because the variable
+names are the same. You can examine the default scripts in
+`/usr/lib/python2.6/​site-packages/​bkr/labcontroller/​power-scripts`
+for inspiration.
+
+
+Netboot config files
+--------------------
+
+Beaker does not use templates for generating bootloader configs when
+provisioning a system (Cobbler's `/etc/cobbler/pxe/pxesystem.template` etc).
+Customizing these configs is not supported.
+
+Unlike Cobbler, Beaker does *not* manage the default bootloader config
+(`$TFTP_ROOT/​pxelinux.cfg/​default`, and equivalent files for other
+bootloaders). You can continue to let Cobbler put its PXE menu here, or you can
+manage this file by hand. Beaker's only requirement for automated provisioning
+is that the it must default to local booting with a sensible timeout (the
+Cobbler PXE menu does this).
+
+
+Snippets
+--------
+
+Snippets are now located on the Beaker server (rather than the lab controller),
+under `/etc/beaker/snippets`.
+
+Beaker uses Jinja2 for templating, so templates will need to be rewritten.
+Refer to the [Jinja2 documentation](http://jinja.pocoo.org/docs/) for details
+of the template syntax, and to [Customizing
+Kickstarts](guide/Administration-Customizing_Kickstarts.html) in the Beaker
+Guide for details about the Beaker specifics.
+
+For your convenience, some common Cobbler template constructs are shown below,
+along with their equivalent in Beaker.
+
+Accessing a variable:
+
+    $getVar('ondisk', '')
+
+    {{ ondisk }}
+
+Looping:
+
+    #set _devices = $getVar('scsidevices', '').split(',')
+    #for $device in $_devices:
+    device $device
+    #end for
+
+    {% for device in scsidevices|split(',') %}
+    device {{ device }}
+    {% endfor %}
+
+Conditional on distro version:
+
+    #if $os_version == "rhel3"
+    #set $yum = "yum-2.2.2-1.rhts.EL3.noarch.rpm"
+    #end if
+
+    {% if distro is osmajor('RedHatEnterpriseLinux3') %}
+    {% set yum = 'yum-2.2.2-1.rhts.EL3.noarch.rpm' %}
+    {% endif %}
+
+
+Other Cobbler system management features
+----------------------------------------
+
+Cobbler's func integration, managed config files, and RHN registration features
+are incompatible with Beaker.
+
+DHCP and DNS services are outside the scope of Beaker, so if you are using
+Cobbler to manage these in the lab then you can continue to do so. However, if
+you are relying on Cobbler's network config scripts when provisioning systems
+(that is, the `pre_​install_​network_​config`,
+`network_​config`, and `post_​install_​network_​config`
+snippets) you must migrate this configuration to DHCP instead.
+
+If a system has particular network configuration needs not covered by DHCP, you
+can add a per-system snippet for it as appropriate: `system_pre` for
+pre-installation scripts, `network` for Anaconda network commands, or
+`system_post` for post-installation scripts. Refer to [Customizing
+Kickstarts](guide/Administration-Customizing_Kickstarts.html) in the Beaker
+Guide for details.
+
+<!-- vim: set filetype=markdown : -->