psj.site Installation
***********************

How to install psj.site inside another package
================================================

To install psj.site into the global Python environment (or a workingenv),
using a traditional Zope 2 instance, you can do this:

 * When you're reading this you have probably already run 
   ``easy_install psj.site``. Find out how to install setuptools
   (and EasyInstall) here:
   http://peak.telecommunity.com/DevCenter/EasyInstall

 * If you are using Zope 2.9 (not 2.10), get `pythonproducts`_ and install it 
   via::

       python setup.py install --home /path/to/instance

   into your Zope instance.

 * Create a file called ``psj.site-configure.zcml`` in the
   ``/path/to/instance/etc/package-includes`` directory.  The file
   should only contain this::

       <include package="psj.site" />

.. _pythonproducts: http://plone.org/products/pythonproducts


Alternatively, if you are using zc.buildout and the plone.recipe.zope2instance
recipe to manage your project, you can do this:

 * Add ``psj.site`` to the list of eggs to install, e.g.:
 
    [buildout]
    ...
    eggs =
        ...
        psj.site
        
  * Tell the plone.recipe.zope2instance recipe to install a ZCML slug:
  
    [instance]
    recipe = plone.recipe.zope2instance
    ...
    zcml =
        psj.site
        
  * Re-run buildout, e.g. with:
  
    $ ./bin/buildout
        
You can skip the ZCML slug if you are going to explicitly include the package
from another package's configure.zcml file.

Note, that the real installation is quite cumbersome, because it is
based on the collaboration with OpenOffice.org. See below to see, how
you can install psj.site in detail.


Installing psj.site via ``buildout``
======================================

We describe an installation on a freshly installed Ubuntu
system. Windows(TM) systems are not supported by time of writing
this.

1) Install the base system.

  We are using Ubuntu 6.06 server with LTS (Long time support)
  here. This means less stuff on your machine. The whole system
  described below will need less than 2.5 GB disk space.

  Make sure you choose `English (US)` as base system. Otherwise you
  will have to tweak the tests lateron. This is caused by OOos
  'intelligent' locale detection, which produces different documents
  depending on your system locale. The tests here rely on the US
  locale.

  Afterwards setup ``/etc/apt/sources.list`` so, that universe and
  multiverse repositories are included.

  Then, as superuser, run::

     # apt-get update

  to fetch the list of the newly added repositories.

  During base install we created a user `zope`.

2) Install additional packages:

  We need Python2.4. On our system this is the default version.  So we
  only have to do::

     # apt-get install python2.4-dev

  to get the headers for building Zope. More current distributions
  often come with Python2.5 as default and do not offer any Python2.4
  packages any more. In this case you have to grab the sources from
  the net and install Python2.4 by yourself.

  After Python is installed, you should be able to type::

     $ python2.4

  without an error message.

  Then, as superuser, do::

     # apt-get install subversion rpm unzip gcc libc6-dev \
                       libxslt1.1 libxslt1-dev xsltproc \
                       libsm6 sun-java5-bin \
                       libjpeg62 libjpeg62-dev libfreetype6 \
                       libfreetype6-dev \
                       xvfb python2.4-profiler wv

  These are the generally needed packages for building and running
  ``psj.site``. Some may be already installed on your
  system. Concerning the Java package (above Sun Java 1.5 is
  installed) you might get along with a different one.

  The libsm6 and xvfb packages are needed for the X-server
  requirements of OOo. You don't have to run a X-server with this
  installation, not even a framebuffer server, but some libs are
  nonetheless needed by OOo to start. The xvfb package includes all
  this packages, so it's easier to include it.

  If you already have a running X-server on your system, then you
  don't have to install libsm6 nor xvfb.

  The profiler is needed only, if you want to run the tests, which is
  warmly recommended.

  The `wv` package contains converters for alien formats like doc and
  xsl. It is currently used by transforms for MS based documents.

  We also install:: 

     # apt-get install openssh-server

  to be able access the machine remotely.


3) Fetch, build and install ``psj.site``

  Now it's time to get the real code. As a normal user do::

     $ svn co https://svn.gnufix.de/repos/psj.site/trunk \
              psj.site

  This should populate your directory with a new subdir
  ``psj.site``. Now change to it and run the bootstrapper::

     $ cd psj.site
     $ python2.4 bootstrap/bootstrap.py

  This will create the ``buildout`` script and some subdirs. Run the
  buildout script::

     $ ./bin/buildout

  It will take a long time, because it has to fetch many, many
  packages and also a complete openoffice package of about 130 MB.

  There are a few things that will still stop the package from
  working. This is explained below in detail. If you want it the short
  way, just run

     $ sudo ./bin/oooprepare

  and you should be done. This script does all the things
  automatically, which are explained below. No worries if you see a
  bunch of complaints saying 'libbla.so is not a symlink', this is
  normal and should not be a problem. Proceed to the next step.

  ..note:: Running `oooprepare` and `ooorestore` should not be 
           necessary any more.

    We now set the OOo `program` directory as LD_LIBRARY_PATH
    environment variable when starting an instance (regular one or ZEO
    client). This is set in `buildout.cfg` and requires, that there
    are no other badly needed paths already stored in this variable.

  To make the freshly created uno package available, you have to
  register the libs in the ``parts/openoffice/program``
  directory. This can be done as superuser::

     # ldconfig /home/zope/psj.site/parts/openoffice/program

  or whatever the path on your system looks like.

  When you're done, the following should work without error::

     $ ./bin/zopepy
     
     >>> import uno

  What will *not* work, is the following::

     $ ./bin/zopepy

     >>> from lxml import etree

  This is, because OOo comes with (rather old) replacements for the
  XSLT and XML2 libs, which are normally already installed (in newer
  versions) on a recent Linux system. Therefore, we **remove** those
  OOo libs:: 

     $ rm parts/openoffice/program/libxslt.so*
     $ rm parts/openoffice/program/libxml2.so*

  Afterwards, both examples mentioned above should work.


4) Start the OOo server

  Now we should be able to start the OOo server::

     $ ./bin/oooctl start


5) Test the code

  Run::

     $ ./bin/instance test -s psj.policy
     $ ./bin/instance test -s psj.content


It might happen, that you experience some wierd problems after running
all this stuff on your computer. For example Firefox might refuse to
start or similar. In this cases it is most likely, that the (somewhat
old) libraries from the OOo package are loaded and not the same named
and more recent system packages. In this case run

   $ sudo ./bin/ooorestore

and everything should be okay. Running `ooorestore` is only needed, if
you have run `oooprepare` before.


Installing psj.site as ZEO-cluster via ``buildout``
===================================================

In this section we explain how to setup a PSJ site as a ZEO
cluster. It is recommended to install a single instance as shown in
the section above and run all tests. This way you can make sure, that
there are no ZEO-specific flaws in your setup.

ZEO-support is provided by a specialized buildout-configuration, that
can be found in `buildout-zeo.cfg`.

1) Follow steps 1) and 2) of the section above to have a basic system
   working. 

2) Fetch, build and install ``psj.site``

  Now it's time to get the real code. As a normal user do::

     $ svn co https://svn.gnufix.de/repos/psj.site/trunk \
              psj.site

  This should populate your directory with a new subdir
  ``psj.site``. Now change to it and run the bootstrapper::

     $ cd psj.site
     $ python2.4 bootstrap/bootstrap.py

  This will create the ``buildout`` script and some subdirs.

3) Setup ZEO, part1: prepare `buildout-zeo.cfg`

  ZEO-support is provided by a specialized buildout-configuration,
  that can be found in `buildout-zeo.cfg`.

  Visit the `buildout-zeo.cfg` file. It provides by default one ZEO
  server running on port 8100 and two ZEO client instances running on
  ports 8080 and 8081. You might want to change the
  ports or other values as appropriate to your very special setup.

  The single options are documented.

  If you want to have more client instances, just cut and paste the
  `[zeoclient2]` section and change the name to `[zeoclient3]` or
  whatever suits your needs best. Do not forget to add the new entry
  in the `parts` parameter of the top-most `buildout` section.

4) Setup ZEO, part2: deploy the ZEO configuration

  Now you can run `buildout` with the freshly modified
  buildout configuration

     $ ./bin/buildout -c buildout-zeo.cfg

  This installs the ZEO infrastructure as described above.

5) Prepare the OOo-environment and start the OOo-server

  Before we can really run the whole environment, we have to prepare
  the OOo-specific environment. Follow parts 3) and 4) of the above
  section to complete this task.

  Normally you should only have to do::

    $ sudo ./bin/oooprepare
    $ ./bin/oooctl start

  Afterwards you should have a running
  OOo server.

6) Start the ZEO server and clients

  When the OOo-server has started, just do::

    $ ./bin/zeoserver start
    $ ./bin/zeoclient1 start
    $ ./bin/zeoclient2 start

7) Stopping the whole thing

  Stop the services in reverse order:

    $ ./bin/oooctl stop
    $ sudo ./bin/ooorestore
    $ ./bin/zeoclient2 stop
    $ ./bin/zeoclient1 stop
    $ ./bin/zeoserver stop
