Index: in/waeup.aaua/trunk/README-zeo.txt
===================================================================
--- /main/waeup.aaua/trunk/README-zeo.txt	(revision 11322)
+++ 	(revision )
@@ -1,156 +1,0 @@
-Deploying waeup.aaua as ZEO-install
-*************************************
-
-Each ZEO install consists of at least one ZEO server and normally two
-or more ZEO clients. While the ZEO server is meant to manage the ZODB
-database for clients, the clients connect to the outside world, listen
-for request and do the real dataprocessing.
-
-We prepared a `buildout` configuration that sets up one server
-configuration and two client configs. This configuration is in
-``buildout-zeo.cfg``.
-
-Generating the ZEO setup
-========================
-
-To install waeup.aaua ZEO-based you can run `buildout` with the given
-(or your own) configuration file like this::
-
-  $ ./bin/buildout -c buildout-zeo.cfg
-
-This should generate all scripts necessary to run servers, clients,
-etc.
-
-Starting ZEO servers and clients
-================================
-
-First start the server::
-
-  $ ./bin/zeo_server start
-
-Clients can be started by doing::
-
-  $ ./bin/zeo_client1 start
-  $ ./bin/zeo_client2 start
-
-This will start both clients in daemon mode.
-
-Instead of ``start`` you can, as usually, start an instance in
-foreground (``fg``), etc. You know the drill.
-
-Manually starting ZEO clients
------------------------------
-
-This is normally not neccessary.
-
-``zeo_clientN`` scripts are basically wrappers around calls to
-``bin/paster``. You can bypass this wrapper and start a client
-'manually' like this::
-
-  $ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
-        pars/etc/zeo1.ini
-
-It is important to give a pid-file as paster otherwise can not start
-different clients (they would all refer to the same pid file
-`paster.pid` and refuse to start after the first client was started).
-
-
-Setup (paramters, ports, etc.)
-==============================
-
-By default the server will listen on port 8100 for requests from
-localhost (not: from the outside world).
-
-You can change ZEO server settings in the ``[zeo_server]`` section
-of ``buildout-zeo.conf``. Run `buildout` afterwards.
-
-The clients will listen on port 8081 and 8082. You can change settings
-in ``etc/zeo1.ini.in`` and ``etc/zeo2.ini.in`` respectively. Run
-buildout after any change.
-
-If you want to change the paster wrapper for any zeo client, you can
-edit ``etc/zeo1.conf`` and/or ``etc/zeo2.conf``. Run buildout
-afterwards.
-
-Creating new clients
-====================
-
-You want more clients to be created by buildout? Easy. Three steps are
-neccessary.
-
-1. Create config files in etc/
-------------------------------
-
-Each client needs two configuration files:
-
-  - ``etc/zeoN.conf``
-       configuring the paster wrapper
-
-  - ``etc/zeoN.ini``
-       configuring the runtime config, ports, etc.
-
-Just copy over these files from the already existing zeo1/zeo2 files
-and replace ``zeo1`` or ``zeo2`` with your new name.
-
-2. Update buildout-zeo.cfg
---------------------------
-
-Here, inside ``buildourt-zeo.cfg`` also three steps are needed.
-
-* 2.1. Create new .ini and .conf entries
-
-  The .conf and .ini files in etc/ are only templates that have to be
-  generated in their really used final location. In buildout-zeo.cfg
-  you can care for this by creating a new ``[zeoN_ini]`` and
-  ``[zeoN_conf]`` option (replacing ``N`` with a number, of course).
-
-  Just copy over existing entries and replace the mentions of ``zeo1``
-  or ``zeo2`` by your ``zeoN``.
-
-* 2.2. Create a new ``zeo_clientN`` entry
-
-  Then you have to create an entry that will generate the
-  ``zeo_clientN`` script. Again, just copy over an existing
-  ``[zeo_client1]`` entry and replace ``1`` withg your client number.
-
-* 2.3. Register the new sections in ``[buildout]`` section
-
-  When done with the above: add the new section in ``[buildout]``::
-
-    [buildout]
-      ...
-      <old entries...>
-      ...
-      zope_conf_zeo_5
-      zeo5_ini
-      zeo_client5
-
-  depending on how you named your new sections.
-
-3. Rerun ``buildout``
----------------------
-
-When adding or removing client/server instances, make sure to stop all
-running servers/clients before rerunning buildout.
-
-To activate the new setup, rerun buildout::
-
-  $ bin/buildout -c buildout-zeo.cfg
-
-This should generate any new clients and remove older ones or just
-update configuration files.
-
-
-Considerations
-==============
-
-There are some things in the current buildout-zeo.cfg we might do not
-want. It extends the regular ``buildout.cfg`` so that we do not have
-to repeat most sections but the ``parts`` in ``[buildout]`` have to be
-listed.
-
-We need, however, not everything with a ZEO-deploy that is listed in a
-default buildout. We might do not need docs, no profiling, etc. Also a
-regular non-ZEO kofactl might not make to much sense. Therefore all
-this might be subject to changes.
-
Index: /main/waeup.aaua/trunk/README.html
===================================================================
--- /main/waeup.aaua/trunk/README.html	(revision 11323)
+++ /main/waeup.aaua/trunk/README.html	(revision 11323)
@@ -0,0 +1,659 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
+<title>Installation of Kofa on Linux production system</title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+  border: 0 }
+
+table.borderless td, table.borderless th {
+  /* Override padding for "table.docutils td" with "! important".
+     The right padding separates the table cells. */
+  padding: 0 0.5em 0 0 ! important }
+
+.first {
+  /* Override more specific margin styles with "! important". */
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
+  overflow: hidden;
+}
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+  font-weight: bold }
+*/
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin: 0 0 0.5em 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left, .figure.align-left, object.align-left {
+  clear: left ;
+  float: left ;
+  margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right {
+  clear: right ;
+  float: right ;
+  margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+  text-align: left }
+
+.align-center {
+  clear: both ;
+  text-align: center }
+
+.align-right {
+  text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+  text-align: inherit }
+
+/* div.align-center * { */
+/*   text-align: left } */
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font: inherit }
+
+pre.literal-block, pre.doctest-block, pre.math {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid 1px gray;
+  margin-left: 1px }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid 1px black;
+  margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+ul.auto-toc {
+  list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="installation-of-kofa-on-linux-production-system">
+<h1 class="title">Installation of Kofa on Linux production system</h1>
+
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last"><cite>waeup.kofa</cite> and its custom packages
+might not work with Python &gt; 2.7
+currently. Use of Python 2.7 is recommended.
+The installation is described for Linux-based computers.</p>
+</div>
+<div class="section" id="part-1-deploying-kofa-as-a-single-zope-client-install">
+<h1>Part 1: Deploying Kofa as a single Zope client install</h1>
+<div class="section" id="prerequisites">
+<h2>Prerequisites</h2>
+<p>The Kofa packages are based on <a class="reference external" href="http://grok.zope.org/">Grok</a>, which is a Python
+framework for agile webapplication development. Grok itself is based
+on <a class="reference external" href="http://www.zope.org/">Zope</a>.</p>
+<p>Both, Grok and Zope, are written in Python (with parts written in
+C). You therefore need <a class="reference external" href="http://www.python.org/">Python</a> installed.</p>
+<p>Note, that you also need the Python header files and a compiler to
+compile the parts written in C.</p>
+<p>To deploy Kofa most easily, we use <a class="reference external" href="http://cheeseshop.python.org/pypi/zc.buildout">zc.buildout</a></p>
+</div>
+<div class="section" id="preparing-the-system">
+<h2>Preparing the system</h2>
+<p>To create a working copy of Kofa we recommend use of
+<cite>virtualenv</cite>. You, however, need also some basic libraries, a C
+compiler and some things more.</p>
+<p>What you need (Debian/Ubuntu package names in brackets):</p>
+<ul>
+<li><p class="first">Python 2.7 (python2.7)</p>
+</li>
+<li><p class="first">Python 2.7 development files (python2.7-dev)</p>
+</li>
+<li><p class="first">A C-Compiler (gcc)</p>
+</li>
+<li><p class="first">The C library development files (libc6-dev)</p>
+</li>
+<li><p class="first">A subversion client (svn)</p>
+</li>
+<li><p class="first">enscript (enscript) [optional]</p>
+<p>This is only needed if you want test coverage reports.</p>
+</li>
+</ul>
+<p>All these packages can be installed on Debian systems like this:</p>
+<pre class="literal-block">
+# apt-get install python2.7 python2.7-dev python2.7-dbg \
+                  gcc libc6-dev svn enscript
+</pre>
+<p>Afterwards you should be able to enter:</p>
+<pre class="literal-block">
+$ python2.7
+</pre>
+<p>at the commandline and get a Python prompt. Quit the interpreter
+pressing &lt;CTRL-D&gt;.</p>
+</div>
+<div class="section" id="installing-virtualenv">
+<h2>Installing <cite>virtualenv</cite></h2>
+<p>We recommend use of <cite>virtualenv</cite> to create Python sandboxes where you
+can run your code without touching any other installations.</p>
+<p>If you don't already have <tt class="docutils literal">easy_install</tt> available, you can find the
+script to set it up on the <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install">PEAK EasyInstall page</a>.</p>
+<p>You need to download <a class="reference external" href="http://peak.telecommunity.com/dist/ez_setup.py">ez_setup.py</a>. Then, you run it like this to
+install <tt class="docutils literal">easy_install</tt> into your system Python:</p>
+<pre class="literal-block">
+$ sudo python2.7 ez_setup.py
+</pre>
+<p>This will make <tt class="docutils literal">easy_install</tt> available to you.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>Sometimes you have <tt class="docutils literal">easy_install</tt> installed but you need a
+newer version of the underlying setuptools infrastructure to
+make Grok work. You can upgrade setuptools with:</p>
+<pre class="last literal-block">
+$ sudo easy_install -U setuptools
+</pre>
+</div>
+<p>Now you can install <cite>virtualenv</cite> by doing (as root):</p>
+<pre class="literal-block">
+# easy_install-2.7 virtualenv
+</pre>
+<p>This step will fetch all needed sources from the internet and install
+<cite>virtualenv</cite> locally in your Python2.7 installation.</p>
+</div>
+<div class="section" id="creating-a-sandbox">
+<h2>Creating a sandbox</h2>
+<p>This step is only necessary (and recommended) if you installed
+<cite>virtualenv</cite> before.</p>
+<p>As a normal user you now can create a sandbox for your upcoming work
+by:</p>
+<pre class="literal-block">
+$ virtualenv --no-site-packages mysandbox
+</pre>
+<p>where <tt class="docutils literal">mysandbox</tt> is a directory in the filesystem where your
+sandbox will be created. <cite>virtualenv</cite> will also create this directory
+for you.</p>
+<p>By passing the <tt class="docutils literal"><span class="pre">no-site-packages</span></tt> switch we tell <cite>virtualenv</cite> to
+provide us a clean environment without any extra-packages installed
+systemwide.</p>
+<p>You now can activate the sandbox by doing:</p>
+<pre class="literal-block">
+$ source mysandbox/bin/activate
+</pre>
+<p>You will notice that the input prompt changes.</p>
+<p>To deactivate the sandbox at any time, enter:</p>
+<pre class="literal-block">
+(sandbox27)$ deactivate
+</pre>
+<p>and the prompt will be the same as before the activation.</p>
+<p>For the following steps make sure the sandbox is active.</p>
+</div>
+<div class="section" id="creating-a-working-place">
+<h2>Creating a working place</h2>
+<p>In the sandbox we now create our real working
+environment. To do this, we change to the sandbox and checkout the
+sources of Kofa from the subversion server:</p>
+<pre class="literal-block">
+(sandbox27)$ cd mysandbox/
+(sandbox27)$ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk kofa-trunk
+</pre>
+<p>where <tt class="docutils literal"><span class="pre">kofa-trunk</span></tt> is only a name we've chosen here to make clear
+where the sources come from. In this case we are installing the Kofa base
+package.</p>
+<p>The command should fetch the Kofa base package sources for you and
+put it in the directory <tt class="docutils literal"><span class="pre">kofa-trunk/</span></tt>.</p>
+<p>Now enter the new directory:</p>
+<pre class="literal-block">
+(sandbox27)$ cd kofa-trunk
+</pre>
+</div>
+<div class="section" id="preparing-the-build">
+<h2>Preparing the build</h2>
+<p>In the sources directory (<tt class="docutils literal"><span class="pre">kofa-trunk/</span></tt>) you have to prepare the
+project to fetch needed components (eggs), compile C-code parts,
+etc. This steip will not touch any external projects:</p>
+<pre class="literal-block">
+(sandbox27)$ python bootstrap.py
+</pre>
+<p>This will generate some directories and the <tt class="docutils literal">buildout</tt> script in
+<tt class="docutils literal">bin/</tt> for us. This step must be executed only once for each
+instance.</p>
+<p>You can now deactivate the sandbox:</p>
+<pre class="literal-block">
+(sandbox27)$ deactivate
+</pre>
+<p>Now we can do the real build by triggering:</p>
+<pre class="literal-block">
+$ bin/buildout
+</pre>
+<p>If this is your first install of some Grok-related project, this step
+will need some time as lots of sources have to be fetched, many
+components must be compiled, etc.</p>
+<p>This step must be redone whenever you change something in
+<tt class="docutils literal">buildout.cfg</tt> or <tt class="docutils literal">setup.py</tt>.</p>
+<p>Note that if you have more than one sandbox for a Zope-based web
+application, it will probably make sense to share the eggs between the
+different sandboxes.  You can tell <tt class="docutils literal">zc.buildout</tt> to use a central
+eggs directory by creating <tt class="docutils literal"><span class="pre">~/.buildout/default.cfg</span></tt> with the
+following contents:</p>
+<pre class="literal-block">
+[buildout]
+eggs-directory = /home/bruno/buildout-eggs
+</pre>
+</div>
+<div class="section" id="start-the-instance">
+<h2>Start the instance</h2>
+<p>You should be able now to start the created instance by doing:</p>
+<pre class="literal-block">
+$ bin/zopectl fg
+</pre>
+<p>Alternatively you can do:</p>
+<blockquote>
+$ bin/paster serve parts/etc/deploy.ini</blockquote>
+<p>The port numbers where Kofa is running on your server are defined in
+buildout.cfg under [kofa_params].</p>
+<p>If you now point a browser to the right port on your server, for example</p>
+<pre class="literal-block">
+localhost:8080
+</pre>
+<p>you should get a login pop-up, where you can login as superuser with
+<tt class="docutils literal">grok</tt> and <tt class="docutils literal">grok</tt> as username/password (Kofa base package only!).</p>
+<p>You can stop the instance by pressing &lt;CTRL-C&gt;.</p>
+<p>If you are connected and logged in,
+you should be able to add the grok-based applications
+(such as <tt class="docutils literal">University</tt>) from the menu.</p>
+<p>Add an instance of <tt class="docutils literal">University</tt> and click on the link next to the
+then visible entry in the list of installed applications.</p>
+</div>
+<div class="section" id="running-the-tests">
+<h2>Running the tests</h2>
+<p>The tests are easily run by executing the test runner that's
+installed in the <tt class="docutils literal">bin</tt> directory:</p>
+<pre class="literal-block">
+$ bin/test
+</pre>
+</div>
+</div>
+<div class="section" id="part-2-deploying-kofa-as-zeo-install">
+<h1>Part 2: Deploying Kofa as ZEO install</h1>
+<p>Each ZEO install consists of at least one ZEO server and normally two
+or more ZEO clients. While the ZEO server is meant to manage the ZODB
+database for clients, the clients connect to the outside world, listen
+for request and do the real dataprocessing.</p>
+<p>We prepared a <cite>buildout</cite> configuration that sets up one server
+configuration and two client configs. This configuration is in
+<tt class="docutils literal"><span class="pre">buildout-zeo.cfg</span></tt>.</p>
+<div class="section" id="generating-the-zeo-setup">
+<h2>Generating the ZEO setup</h2>
+<p>To install Kofa ZEO-based you can run <cite>buildout</cite> with the given
+(or your own) configuration file like this:</p>
+<pre class="literal-block">
+$ ./bin/buildout -c buildout-zeo.cfg
+</pre>
+<p>This should generate all scripts necessary to run servers, clients,
+etc.</p>
+</div>
+<div class="section" id="starting-zeo-servers-and-clients">
+<h2>Starting ZEO servers and clients</h2>
+<p>First start the server:</p>
+<pre class="literal-block">
+$ ./bin/zeo_server start
+</pre>
+<p>Clients can be started by doing:</p>
+<pre class="literal-block">
+$ ./bin/zeo_client1 start
+$ ./bin/zeo_client2 start
+</pre>
+<p>This will start both clients in daemon mode.</p>
+<p>Instead of <tt class="docutils literal">start</tt> you can, as usually, start an instance in
+foreground (<tt class="docutils literal">fg</tt>), etc. You know the drill.</p>
+</div>
+<div class="section" id="manually-starting-zeo-clients">
+<h2>Manually starting ZEO clients</h2>
+<p>This is normally not neccessary.</p>
+<p><tt class="docutils literal">zeo_clientN</tt> scripts are basically wrappers around calls to
+<tt class="docutils literal">bin/paster</tt>. You can bypass this wrapper and start a client
+'manually' like this:</p>
+<pre class="literal-block">
+$ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
+      pars/etc/zeo1.ini
+</pre>
+<p>It is important to give a pid-file as paster otherwise can not start
+different clients (they would all refer to the same pid file
+<cite>paster.pid</cite> and refuse to start after the first client was started).</p>
+</div>
+<div class="section" id="setup-paramters-ports-etc">
+<h2>Setup (paramters, ports, etc.)</h2>
+<p>By default the server will listen on port 8100 for requests from
+localhost (not: from the outside world).</p>
+<p>You can change ZEO server settings in the <tt class="docutils literal">[zeo_server]</tt> section
+of <tt class="docutils literal"><span class="pre">buildout-zeo.conf</span></tt>. Run <cite>buildout</cite> afterwards.</p>
+<p>The clients will listen on port 8081 and 8082. You can change settings
+in <tt class="docutils literal">etc/zeo1.ini.in</tt> and <tt class="docutils literal">etc/zeo2.ini.in</tt> respectively. Run
+buildout after any change.</p>
+<p>If you want to change the paster wrapper for any zeo client, you can
+edit <tt class="docutils literal">etc/zeo1.conf</tt> and/or <tt class="docutils literal">etc/zeo2.conf</tt>. Run buildout
+afterwards.</p>
+</div>
+<div class="section" id="creating-new-clients">
+<h2>Creating new clients</h2>
+<p>You want more clients to be created by buildout? Easy. Three steps are
+neccessary.</p>
+<div class="section" id="create-config-files-in-etc">
+<h3>1. Create config files in etc/</h3>
+<p>Each client needs two configuration files:</p>
+<blockquote>
+<ul>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal">etc/zeoN.conf</tt></dt>
+<dd><p class="first last">configuring the paster wrapper</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal">etc/zeoN.ini</tt></dt>
+<dd><p class="first last">configuring the runtime config, ports, etc.</p>
+</dd>
+</dl>
+</li>
+</ul>
+</blockquote>
+<p>Just copy over these files from the already existing zeo1/zeo2 files
+and replace <tt class="docutils literal">zeo1</tt> or <tt class="docutils literal">zeo2</tt> with your new name.</p>
+</div>
+<div class="section" id="update-buildout-zeo-cfg">
+<h3>2. Update buildout-zeo.cfg</h3>
+<p>Here, inside <tt class="docutils literal"><span class="pre">buildourt-zeo.cfg</span></tt> also three steps are needed.</p>
+<ul>
+<li><p class="first">2.1. Create new .ini and .conf entries</p>
+<p>The .conf and .ini files in etc/ are only templates that have to be
+generated in their really used final location. In buildout-zeo.cfg
+you can care for this by creating a new <tt class="docutils literal">[zeoN_ini]</tt> and
+<tt class="docutils literal">[zeoN_conf]</tt> option (replacing <tt class="docutils literal">N</tt> with a number, of course).</p>
+<p>Just copy over existing entries and replace the mentions of <tt class="docutils literal">zeo1</tt>
+or <tt class="docutils literal">zeo2</tt> by your <tt class="docutils literal">zeoN</tt>.</p>
+</li>
+<li><p class="first">2.2. Create a new <tt class="docutils literal">zeo_clientN</tt> entry</p>
+<p>Then you have to create an entry that will generate the
+<tt class="docutils literal">zeo_clientN</tt> script. Again, just copy over an existing
+<tt class="docutils literal">[zeo_client1]</tt> entry and replace <tt class="docutils literal">1</tt> withg your client number.</p>
+</li>
+<li><p class="first">2.3. Register the new sections in <tt class="docutils literal">[buildout]</tt> section</p>
+<p>When done with the above: add the new section in <tt class="docutils literal">[buildout]</tt>:</p>
+<pre class="literal-block">
+[buildout]
+  ...
+  &lt;old entries...&gt;
+  ...
+  zope_conf_zeo_5
+  zeo5_ini
+  zeo_client5
+</pre>
+<p>depending on how you named your new sections.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="rerun-buildout">
+<h3>3. Rerun <tt class="docutils literal">buildout</tt></h3>
+<p>When adding or removing client/server instances, make sure to stop all
+running servers/clients before rerunning buildout.</p>
+<p>To activate the new setup, rerun buildout:</p>
+<pre class="literal-block">
+$ bin/buildout -c buildout-zeo.cfg
+</pre>
+<p>This should generate any new clients and remove older ones or just
+update configuration files.</p>
+</div>
+</div>
+<div class="section" id="considerations">
+<h2>Considerations</h2>
+<p>There are some things in the current buildout-zeo.cfg we might do not
+want. It extends the regular <tt class="docutils literal">buildout.cfg</tt> so that we do not have
+to repeat most sections but the <tt class="docutils literal">parts</tt> in <tt class="docutils literal">[buildout]</tt> have to be
+listed.</p>
+<p>We need, however, not everything with a ZEO-deploy that is listed in a
+default buildout. We might do not need docs, no profiling, etc. Also a
+regular non-ZEO kofactl might not make to much sense. Therefore all
+this might be subject to changes.</p>
+</div>
+</div>
+</div>
+</body>
+</html>
Index: /main/waeup.aaua/trunk/README.txt
===================================================================
--- /main/waeup.aaua/trunk/README.txt	(revision 11322)
+++ /main/waeup.aaua/trunk/README.txt	(revision 11323)
@@ -1,10 +1,395 @@
-What is `waeup.kofa`?
-*********************
-
-The WAeUP Student Information and Registration Portal. `waeup.kofa` is
-a web-based management tool for managing universities and schools.
-
-The package was created as an effort of the WAeUP group. See
-http://www.waeup.org to learn more about WAeUP.
-
-Installation instructions can be found in the User Documentation (docs folder in the file system).
+Installation of Kofa on Linux production system
+###############################################
+
+.. note:: `waeup.kofa` and its custom packages
+          might not work with Python > 2.7
+          currently. Use of Python 2.7 is recommended.
+          The installation is described for Linux-based computers.
+
+Part 1: Deploying Kofa as a single Zope client install
+******************************************************
+
+Prerequisites
+=============
+
+The Kofa packages are based on `Grok`_, which is a Python
+framework for agile webapplication development. Grok itself is based
+on `Zope`_.
+
+.. _Grok: http://grok.zope.org/
+
+.. _Zope: http://www.zope.org/
+
+Both, Grok and Zope, are written in Python (with parts written in
+C). You therefore need `Python`_ installed.
+
+.. _Python: http://www.python.org/
+
+Note, that you also need the Python header files and a compiler to
+compile the parts written in C.
+
+To deploy Kofa most easily, we use `zc.buildout`_
+
+.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
+
+
+Preparing the system
+====================
+
+To create a working copy of Kofa we recommend use of
+`virtualenv`. You, however, need also some basic libraries, a C
+compiler and some things more.
+
+What you need (Debian/Ubuntu package names in brackets):
+
+* Python 2.7 (python2.7)
+
+* Python 2.7 development files (python2.7-dev)
+
+* A C-Compiler (gcc)
+
+* The C library development files (libc6-dev)
+
+* A subversion client (svn)
+
+* enscript (enscript) [optional]
+
+  This is only needed if you want test coverage reports.
+
+All these packages can be installed on Debian systems like this::
+
+  # apt-get install python2.7 python2.7-dev python2.7-dbg \
+                    gcc libc6-dev svn enscript
+
+Afterwards you should be able to enter::
+
+  $ python2.7
+
+at the commandline and get a Python prompt. Quit the interpreter
+pressing <CTRL-D>.
+
+
+Installing `virtualenv`
+=======================
+
+We recommend use of `virtualenv` to create Python sandboxes where you
+can run your code without touching any other installations.
+
+If you don't already have ``easy_install`` available, you can find the
+script to set it up on the `PEAK EasyInstall page`_.
+
+.. _`PEAK EasyInstall page`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
+
+You need to download `ez_setup.py`_. Then, you run it like this to
+install ``easy_install`` into your system Python::
+
+  $ sudo python2.7 ez_setup.py
+
+.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
+
+This will make ``easy_install`` available to you.
+
+.. note:: Sometimes you have ``easy_install`` installed but you need a
+          newer version of the underlying setuptools infrastructure to
+          make Grok work. You can upgrade setuptools with::
+
+            $ sudo easy_install -U setuptools
+
+Now you can install `virtualenv` by doing (as root)::
+
+  # easy_install-2.7 virtualenv
+
+This step will fetch all needed sources from the internet and install
+`virtualenv` locally in your Python2.7 installation.
+
+
+Creating a sandbox
+==================
+
+This step is only necessary (and recommended) if you installed
+`virtualenv` before.
+
+As a normal user you now can create a sandbox for your upcoming work
+by::
+
+  $ virtualenv --no-site-packages mysandbox
+
+where ``mysandbox`` is a directory in the filesystem where your
+sandbox will be created. `virtualenv` will also create this directory
+for you.
+
+By passing the ``no-site-packages`` switch we tell `virtualenv` to
+provide us a clean environment without any extra-packages installed
+systemwide.
+
+You now can activate the sandbox by doing::
+
+  $ source mysandbox/bin/activate
+
+You will notice that the input prompt changes.
+
+To deactivate the sandbox at any time, enter::
+
+  (sandbox27)$ deactivate
+
+and the prompt will be the same as before the activation.
+
+For the following steps make sure the sandbox is active.
+
+
+Creating a working place
+========================
+
+In the sandbox we now create our real working
+environment. To do this, we change to the sandbox and checkout the
+sources of Kofa from the subversion server::
+
+  (sandbox27)$ cd mysandbox/
+  (sandbox27)$ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk kofa-trunk
+
+where ``kofa-trunk`` is only a name we've chosen here to make clear
+where the sources come from. In this case we are installing the Kofa base
+package.
+
+The command should fetch the Kofa base package sources for you and
+put it in the directory ``kofa-trunk/``.
+
+Now enter the new directory::
+
+  (sandbox27)$ cd kofa-trunk
+
+
+Preparing the build
+===================
+
+In the sources directory (``kofa-trunk/``) you have to prepare the
+project to fetch needed components (eggs), compile C-code parts,
+etc. This steip will not touch any external projects::
+
+  (sandbox27)$ python bootstrap.py
+
+This will generate some directories and the ``buildout`` script in
+``bin/`` for us. This step must be executed only once for each
+instance.
+
+You can now deactivate the sandbox::
+
+  (sandbox27)$ deactivate
+
+Now we can do the real build by triggering::
+
+  $ bin/buildout
+
+If this is your first install of some Grok-related project, this step
+will need some time as lots of sources have to be fetched, many
+components must be compiled, etc.
+
+This step must be redone whenever you change something in
+``buildout.cfg`` or ``setup.py``.
+
+Note that if you have more than one sandbox for a Zope-based web
+application, it will probably make sense to share the eggs between the
+different sandboxes.  You can tell ``zc.buildout`` to use a central
+eggs directory by creating ``~/.buildout/default.cfg`` with the
+following contents::
+
+    [buildout]
+    eggs-directory = /home/bruno/buildout-eggs
+
+
+Start the instance
+==================
+
+You should be able now to start the created instance by doing::
+
+   $ bin/zopectl fg
+
+Alternatively you can do:
+
+    $ bin/paster serve parts/etc/deploy.ini
+
+The port numbers where Kofa is running on your server are defined in
+buildout.cfg under [kofa_params].
+
+If you now point a browser to the right port on your server, for example ::
+
+   localhost:8080
+
+you should get a login pop-up, where you can login as superuser with
+``grok`` and ``grok`` as username/password (Kofa base package only!).
+
+You can stop the instance by pressing <CTRL-C>.
+
+If you are connected and logged in,
+you should be able to add the grok-based applications
+(such as ``University``) from the menu.
+
+Add an instance of ``University`` and click on the link next to the
+then visible entry in the list of installed applications.
+
+Running the tests
+=================
+
+The tests are easily run by executing the test runner that's
+installed in the ``bin`` directory::
+
+    $ bin/test
+
+
+Part 2: Deploying Kofa as ZEO install
+*************************************
+
+Each ZEO install consists of at least one ZEO server and normally two
+or more ZEO clients. While the ZEO server is meant to manage the ZODB
+database for clients, the clients connect to the outside world, listen
+for request and do the real dataprocessing.
+
+We prepared a `buildout` configuration that sets up one server
+configuration and two client configs. This configuration is in
+``buildout-zeo.cfg``.
+
+Generating the ZEO setup
+========================
+
+To install Kofa ZEO-based you can run `buildout` with the given
+(or your own) configuration file like this::
+
+  $ ./bin/buildout -c buildout-zeo.cfg
+
+This should generate all scripts necessary to run servers, clients,
+etc.
+
+Starting ZEO servers and clients
+================================
+
+First start the server::
+
+  $ ./bin/zeo_server start
+
+Clients can be started by doing::
+
+  $ ./bin/zeo_client1 start
+  $ ./bin/zeo_client2 start
+
+This will start both clients in daemon mode.
+
+Instead of ``start`` you can, as usually, start an instance in
+foreground (``fg``), etc. You know the drill.
+
+
+Manually starting ZEO clients
+=============================
+
+This is normally not neccessary.
+
+``zeo_clientN`` scripts are basically wrappers around calls to
+``bin/paster``. You can bypass this wrapper and start a client
+'manually' like this::
+
+  $ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
+        pars/etc/zeo1.ini
+
+It is important to give a pid-file as paster otherwise can not start
+different clients (they would all refer to the same pid file
+`paster.pid` and refuse to start after the first client was started).
+
+
+Setup (paramters, ports, etc.)
+==============================
+
+By default the server will listen on port 8100 for requests from
+localhost (not: from the outside world).
+
+You can change ZEO server settings in the ``[zeo_server]`` section
+of ``buildout-zeo.conf``. Run `buildout` afterwards.
+
+The clients will listen on port 8081 and 8082. You can change settings
+in ``etc/zeo1.ini.in`` and ``etc/zeo2.ini.in`` respectively. Run
+buildout after any change.
+
+If you want to change the paster wrapper for any zeo client, you can
+edit ``etc/zeo1.conf`` and/or ``etc/zeo2.conf``. Run buildout
+afterwards.
+
+
+Creating new clients
+====================
+
+You want more clients to be created by buildout? Easy. Three steps are
+neccessary.
+
+1. Create config files in etc/
+------------------------------
+
+Each client needs two configuration files:
+
+  - ``etc/zeoN.conf``
+       configuring the paster wrapper
+
+  - ``etc/zeoN.ini``
+       configuring the runtime config, ports, etc.
+
+Just copy over these files from the already existing zeo1/zeo2 files
+and replace ``zeo1`` or ``zeo2`` with your new name.
+
+2. Update buildout-zeo.cfg
+--------------------------
+
+Here, inside ``buildourt-zeo.cfg`` also three steps are needed.
+
+* 2.1. Create new .ini and .conf entries
+
+  The .conf and .ini files in etc/ are only templates that have to be
+  generated in their really used final location. In buildout-zeo.cfg
+  you can care for this by creating a new ``[zeoN_ini]`` and
+  ``[zeoN_conf]`` option (replacing ``N`` with a number, of course).
+
+  Just copy over existing entries and replace the mentions of ``zeo1``
+  or ``zeo2`` by your ``zeoN``.
+
+* 2.2. Create a new ``zeo_clientN`` entry
+
+  Then you have to create an entry that will generate the
+  ``zeo_clientN`` script. Again, just copy over an existing
+  ``[zeo_client1]`` entry and replace ``1`` withg your client number.
+
+* 2.3. Register the new sections in ``[buildout]`` section
+
+  When done with the above: add the new section in ``[buildout]``::
+
+    [buildout]
+      ...
+      <old entries...>
+      ...
+      zope_conf_zeo_5
+      zeo5_ini
+      zeo_client5
+
+  depending on how you named your new sections.
+
+3. Rerun ``buildout``
+---------------------
+
+When adding or removing client/server instances, make sure to stop all
+running servers/clients before rerunning buildout.
+
+To activate the new setup, rerun buildout::
+
+  $ bin/buildout -c buildout-zeo.cfg
+
+This should generate any new clients and remove older ones or just
+update configuration files.
+
+
+Considerations
+==============
+
+There are some things in the current buildout-zeo.cfg we might do not
+want. It extends the regular ``buildout.cfg`` so that we do not have
+to repeat most sections but the ``parts`` in ``[buildout]`` have to be
+listed.
+
+We need, however, not everything with a ZEO-deploy that is listed in a
+default buildout. We might do not need docs, no profiling, etc. Also a
+regular non-ZEO kofactl might not make to much sense. Therefore all
+this might be subject to changes.
Index: in/waeup.aaua/trunk/src/waeup/aaua/README.txt
===================================================================
--- /main/waeup.aaua/trunk/src/waeup/aaua/README.txt	(revision 11322)
+++ 	(revision )
@@ -1,4 +1,0 @@
-The waeup.aaua package
-************************
-
-A customized portal software for student registration.
