Building KARL
=============

Prequisites
-----------

- Your own build of Python 2.5.x (or experimentally, Python 2.6.x).
  This Python should include *both* the SSL and SQLite extensions.
  This means, thus, that OpenSSL and SQLite must be installed.

- Command-line binaries for converting PDF, Word, etc.  These include:
  ppthtml, wvWare, pdftotext, ps2ascii, rtf2xml, xls2csv.  Note that
  these binaries must be on the PATH of the user running the KARL
  application server.

- Install the required system libraries (see below).

Required Libraries
------------------

Karl uses the Python Imaging Library, which requires certain system
libraries. Install the development headers for libjpeg and zlib
(required for accepting JPEG and PNG image uploads, respectively). The
command for installing these libraries varies by operating system. On
Ubuntu, use::

    sudo apt-get install libjpeg-dev zlib1g-dev

On CentOS 5, use::

    sudo yum install libjpeg-devel zlib-devel

On Mac OS X, there are apparently various methods of installing
libraries. Try these or some variation:

    port install gd2
    fink install libjpeg

A web search for "pil os x" provides helpful hints. Note that you do
not need to install PIL itself, only the system libraries that PIL
needs. Also note that if you build PIL without the required libraries,
the build will succeed, but certain Karl tests will probably fail. To
rebuild PIL with new libraries, delete ``eggs/PIL*`` and re-run
``bin/buildout``.

Building
--------

On most Mac OS X or Linux systems with compilation tools and Python
2.5 (2.6 supported, with warnings) installed, you can build the
environment using the following steps:

Check out the buildout from Subversion (replace PROJECT with the project
name)::

  svn co svn+ssh://PROJECT@agendaless.com/home/PROJECT/svn/karl3-PROJECT/trunk karl3

``cd`` into the newly checked out ``karl3`` directory::

  cd karl3

Create a ``virtualenv`` using your existing Python within the
``karl3`` directory (obtain the ``virtualenv`` from `PyPI
<http://pypi.python.org/pypi/virtualenv>`_)::

  virtualenv --no-site-packages .

Bootstrap the installation::

  bin/python bootstrap.py

Run the buildout and wait several minutes for it to finish::

  bin/buildout

You will know the buildout finished successfully when it prints the
following::

   Generated script '/Users/chrism/projects/karl3/bin/twill-sh'.
   Generated script '/Users/chrism/projects/karl3/bin/flunc'.
   buildout: Generated interpreter '/Users/chrism/projects/karl3/bin/python-flunc'.

Finally, make a symlink to the correct configuration area.  The
various buildouts associated with KARL have a number of pre-setup
configurations.  For development::

  ln -sfn etc-develop etc

If you are building for production rather than development, redirect
the link.  For example::

    ln -sfn etc-deploy etc

Debugging Build Problems
------------------------

Buildout ``default.cfg`` File in Home ``.buildout`` Directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Make sure you don't have a ~/.buildout/default.cfg file; particularly
one that specifies a "download cache".  If you have one of these, the
wrong eggs may be used during installation and the system won't
install cleanly.  An example of such a symptom::

  Error: There is a version conflict.
  We already have: elementtree 1.2.7-20070827-preview
  but repoze.profile 0.6 requires 'elementtree>=1.2.6,<1.2.7'.
  but supervisor 3.0a6 requires 'elementtree>=1.2.6,<1.2.7'.

If you get an error like this or if you have other ``default.cfg``
related problems, either change the ``~/.buildout/default.cfg`` to
disuse a download cache or move the default.cfg aside temporarily,
then delete the ``karl3`` checkout and start over completely.

Starting
--------

After the build finishes successfully, start the system using
supervisord::

  bin/supervisord

Check if it's come up successfully by using ``supervisorctl``::

  bin/supervisorctl status

If it's up successfully, you should see something like the following
as output from ``supervisorctl``::

   karl                             RUNNING    pid 41565, uptime 0:00:45
   zeo                              RUNNING    pid 41486, uptime 0:02:07

Debugging Startup Problems
--------------------------

``ImportError: Failure linking new module`` at startup (lxml)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This has only been witnessed on Mac OS X.  It usually means that the
build found some existing ``libxml2`` or ``libxslt`` instead of the
one that's compiled by the buildout.  It's unclear how this happens,
but it can be resolved by manually setting the MacOS
``DYLD_LIBRARY_PATH``.  For example, if your cwd is the ``karl3``
directory::

  export DYLD_LIBRARY_PATH=`pwd`/parts/libxml2/lib:`pwd`/parts/libxlst/lib:$DYLD_LIBRARY_PATH

Then restart the servers.

Blob layout related startup issue
---------------------------------

If you see an error like this::

  ValueError: Directory layout `zeocache` selected for blob directory /blob dir,
  but marker found for layout `lawn`

It means you've somehow gotten ZODB 3.9 installed instead of the
required ZODB 3.8.  See the resolution steps above in ``Buildout
default.cfg File in Home .buildout Directory`` above to resolve.

Running The Software
--------------------

To use the software, visit `http://localhost:8000/
<http://localhost:8000>`_ in a browser. (Some customizations of KARL
use `http://localhost:6543/ <http://localhost:6543>`_ instead.) When
you see the login page, log in via username: ``admin``, password:
``admin``. After logging in, you should see the "Communities" page.

Debugging Runtime Failures
--------------------------

The application is up but it won't respond to any HTTP requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Make sure that the ZEO server is started, and that it's listening on
the right port.

Running the Server Without Supervisord
--------------------------------------

To run the "front-end" (the main application), do::

  bin/paster serve etc/karl.ini

To run the "back end" (the ZEO server), do::

  bin/runzeo -C etc/zeo.conf

Keeping Up-To-Date
------------------

If time passes and you'd like to see the changes that have been made
by other developers, you can update your "sandbox" using the
"buildout" command.  From within the ``karl3`` directory::

  svn up
  bin/buildout

The necessary changes will be downloaded.  Then start the servers by
running::

 bin/supervisord

.. or if they're already running::

 bin/supervisorctl reload

In some cases after an update, it may be necessary to run the
``start_over`` script to clear out existing data. If your
sandbox doesn't work properly after updating, run this step to clear
out all existing data (while the ZEO server is running)::

 bin/start_over --yes

Generating Sample Content
-------------------------

For testing purposes, KARL has a utility named ``samplegen`` that adds
randomized sample content to the database. The utility generates
communities, each containing blog entries, wiki pages, calendar events,
and files.

To use the ``samplegen`` utility, type::

 bin/samplegen

Use the "-c" option to control the number of communities generated.
Type ``bin/samplegen --help`` for more option documentation.

Known Issues
------------

Slowness In Firefox With Firebug and Web Developer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Page load times in KARL3 under Firefox appear slow when either Firebug
and/or the Firefox Web Developer toolkit is installed and enabled.
Disable these tools as necessary or use a different browser to see the
actual system speed.

