source: WAeUP_Doc/ExtendedInstructions/1InstallingZope.rst @ 4829

============================================
Installing Zope (for training purposes only)
============================================
-----------------------
A [not so] Quick Primer
-----------------------

To deploy the WAeUP Student Registration Portal on your computer, you
first have to set up a running Zope instance. These are installation
instructions for Windows and Linux. Please note, that the recommended
platform for production use is Linux due to advanced security and
availability of service. However for testing you can freely use the
operating system you like.

General Remarks
---------------

Any running Zope installation consists of at least an installed Zope
binary and a Zope instance. It is important to distinguish Zope
installations from Zope instances. Usually, you only have *one
installation of a certain Zope version* installed (in case of WAeUP:
version 2.9.8), while there might be *several Zope instances* installed
based on the one Zope installation, but located at different locations
in the filesystem.

A special case, common on Windows but unusual on Unix-machines, is, to
install an instance of Zope in the same directory, where the mean Zope
installation is located. For the Zope-administrator it is then
difficult to see a difference between the Zope installation and the
Zope instance, but the difference indeed exists.

Further complications arise from the fact, that the term
'install/start/stop/use Zope' often really means a Zope instance, but
only speaks of 'Zope' in general. You might keep in mind, that after
installing Zope instances and going into production use, you rarely
handle with Zope installations, but mostly with Zope instances. The
thing you start, when you start 'a Zope' is technically a Zope
instance, which in turn deploys a Zope installation. Also the thing,
which answers HTTP-Requests in a running 'Zope-System' is an Zope
instance. Have a look at the following figure:

  .. image:: ./zinstancesetup.png

*Fig. 1: Zope Overload*

A (obviously overloaded) system with two Zope versions installed and
five instances, which listen on five different ports. A browser is
connected to port 8082, which is served by the 'waeup'-instance, which
in turn deploys a Zope 2.9.8 installation (sharing it with two other
instances).


Installing Zope on Windows
---------------------------

TODO

Installing Zope on MacOS X
--------------------------

Mostly the same as on Linux (see below).

  * Your home directory (~) is `/Users/user`.
  
  * You need to install Developer Tools (XCode).
  
  * You need to install wget on your own (perhaps use MacPorts or Fink) or use curl.
  
  * Depending on your OS version you need to install an older Python version,
    perhaps via MacPorts or Fink.
    (*Don't touch Apple's default Python installation!*)

Installing Zope on Linux
------------------------

Zope can be installed and instances be run by any user, who has access
to the system. The highly recommended kind of Zope-install on Linux is
to grab the source code and build the installation on your system
directly.

The install is not as complicated, as the length of this document
might suggest. The length is a result of the authors logorrhoea, not
of overwhelming complexity of the topic.

If you are in a hurry and only want the short version, here are the
essential steps. Log into your system as a normal user, go to your
home directory and do:

  ::

    ~$ wget http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz
    ~$ mkdir -p zope/base zope/build zope/pkgs zope/instances
    ~$ cp Zope-2.9.8-final.tgz zope/build
    ~$ mv Zope-2.9.8-final.tgz zope/pkgs   
    ~$ cd zope/build
    ~/zope/build$ tar -xzf Zope-2.9.8-final.tgz
    ~/zope/build$ cd Zope-2.9.8-final
    ~/zope/build/Zope-2.9.8-final$ ./configure --prefix=/home/user/zope/base/2_9_8
    ~/zope/build/Zope-2.9.8-final$ make
    ~/zope/build/Zope-2.9.8-final$ make install
    ~/zope/build/Zope-2.9.8-final$ /home/user/zope/base/2_9_8/bin/mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret
    ~/zope/build/Zope-2.9.8-final$ /home/user/zope/instances/myinstance1/bin/zopectl start

  *Fig. 2: Zope install on Linux / Short version*

This should work on most systems. However, there are many error
sources and if something goes wrong, you have to understand what is
happening in each of steps. Explaining this is something, long
versions are made for.


  1. *Get the sources*

     Get the Zope sources from `http://www.zope.org/`. For the
     WAeUP-portal you currently need the 2.9.8 version of Zope, which can
     be found here: `http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz`

     Using the commandline you might change to your home directory (`cd`) and
     do (the dollar-sign here and elsewhere denotes the commandline
     prompt, the tilde in front of the dollar sign means: 'home directory'):

       ::

         ~$ cd
         ~$ wget http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz
         --16:03:00--  http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz
               => `Zope-2.9.8-final.tgz'
         Resolving www.zope.org... 63.240.213.171
         Connecting to www.zope.org|63.240.213.171|:80... connected.
         HTTP request sent, awaiting response... 200 OK
         Length: 8,010,113 (7.6M) [application/x-gzip]

         100%[====================================>] 8,010,113    203.30K/s    ETA 00:00

         16:03:50 (156.42 KB/s) - `Zope-2.9.8-final.tgz' saved [8010113/8010113]


  2. *Create a Zope directory tree*

     If you did not do already, it is adviceable to create a directory
     structure which enables you to find all your Zope installations
     and instances at a well defined place. Otherwise you might get
     lost in the many directories and subdirectories usually created
     by Zope.

     You can indeed use the tool of your choice for creating
     directories. For example the file-manager of your favourite window
     manager. Note however, that on many servers, you might going to
     administer on the internet later on, there is no such thing like
     a GUI installed (for good reason: GUIS on servers are
     unneccessary performance killers). I therefore, in the following
     example, show, how to create the directory structure on the
     commandline.

     We create the following directory structure:

     .. image:: ./zopedirtree1.png

     The directory tree contains a common subdirectory 'zope/' to keep
     all Zope related stuff apart from other user related data. It
     ends up in four leafs, which purposes are as follows:

       * *base/ -- The Zope installation directory*

         This directory holds the finished (compiled etc.) Zope
         installations (*not* the instances which have got their own
         directory). It will later on contain one subtree for each
         Zope version installed.

       * *build/ -- Helper directory for building Zope from source*

         This directory will be the place, where we start the
         installation. Its purpose is to have a place, where we can
         build (compile etc.) Zope, without having too much unused
         files laying around. Strictly speaking, after having built
         and installed Zope once, there is no need to keep the
         building directory and you might remove it afterwards.

       * *pkgs/ -- Repository for packages downloaded*

         Also this directory is not neccessary, to build
         Zope. It is a place to store packages, downloaded from the
         internet, especially Zope products or Zope
         source-tarballs. It comes in handy, if you want to keep
         packages for later use. We will use it to keep a backup of
         the Zope sources and CPS products, so we do not have to
         download them from internet everytime we create a new
         instance. 

       * *instances/ -- The Zope instances directory*

         The most important directory in daily use. Here we create our
         Zope instances and here we will spend the most time, once,
         one or more insances are created and run.

     As you might already guessed, there is no need to create such a
     directory structure. Furthermore you can give the directories
     other names, whatever you like. In daily work it turned out, that
     such a directory tree is very handy and it tends to be a kind of
     best practice, to use it.

     On the commandline the directory tree is created like so:

       ::

         ~$ mkdir zope
         ~$ mkdir zope/base zope/build zope/pkgs zope/instances

  3. *Unpack the sources*

     The sources are packed in a so-called 'tarball', which is denoted
     by the file extension 'tgz', a short form of 'tar.gz'.

     Now, as we freshly created a directory for building, we first copy
     the downloaded tarball containing the Zope sources to the build
     directory: 

       ::

         ~$ cp Zope-2.9.8-final.tgz zope/build

     Afterwards we put the sources into the pkgs-directory to keep it
     for later use (and remove it from our home directory):

       ::

         ~$ mv Zope-2.9.8-final.tgz zope/pkgs

     The command 'mv' *moves* a file to a different location, thereby
     deleting the old file.

     Now we can change to the build-directory and unpack the sources:

       ::

         ~$ cd zope/build
         ~/zope/build$ tar -xzf Zope-2.9.8-final.tgz

     The commandline options 'xzf' mean: e(x)tract the file, un(z)ip the
     file and do the whole operation on the (f)ile Zope-2.9.8-final.tgz.

     This creates a new subdirectory 'Zope-2.9.8-final' with all required
     sources.

  4. *Build Zope base*

     Change to the sources directory:

       ::

         ~/zope/build$ cd Zope-2.9.8-final

     Here you can find a file configure, which is most important, to
     get all compile time options, supported by your Zope version. You
     can view them by calling './configure --help':

       ::

         ~/zope/build/Zope-2.9.8-final$ ./configure --help

         configure [--help] [--quiet] [--with-python=path] [--prefix=path]

         Create a Makefile suitable for building Zope

         Options:
          --help              shows usage and quits
          --quiet             suppress nonessential output
          --with-python       specify a path to a Python interpreter to use
          --prefix            specify an installation path for binary data

         Given no options, configure will search your PATH for a suitable
         Python interpreter and use '/usr/local/Zope-2.9.8-final' as a prefix.

     Basically, it tells you, that you can give a special Python
     version to build Zope and an installation path. Usually, it is
     best to let the configure script look for an appropriate Python
     interpreter.

     Note, that for building Zope you not only have to provide a
     running Python interpreter (preferably version 2.4.3), but also
     the header files and related developer files of your Python
     installation. Usually on Linux those packages are called
     python-dev or similar. The exact package name depends on your
     distribution. 

     On Debian/Ubuntu based systems you can install the package
     'python2.4-dev', which has to be done as superuser (denoted by
     the '#'-sign in the follwing):

       ::

         ~# apt-get install python2.4-dev

     While the Python developer files are rarely installed on usual
     end-user systems (except Zope users), the most systems already
     have a C-compiler (most common on Linx: gcc) installed, which you
     need too to build Zope. If Zope complains while building about
     unknown files or similar, make sure you have intalled the 'gcc'
     and the Python developer files. Consult your distributions'
     documentation to learn, how to do this.

     To start the real built, we give the 'configure'-script a
     prefix-option, which tells, that we want to have installed Zope
     in the base/ directory:

       ::

         ~/zope/build/Zope-2.9.8-final$ ./configure --prefix=/home/user/zope/base/2_9_8

     Here we want Zope to be installed in
     /home/user/zope/base/2_9_8. Note, that the path
     /home/user/zope/base/ must already exist before executing the
     above command, while the subdirectory '2_9_8' (yes, its a
     diretory name) should be created by the build process.

     You can however use any name you want for your Zope installation,
     for example 'zope293' or something similar. Just change the
     prefix-parameter in that case accordingly.

     If everthing went well, you got the following (or similar) output:

       ::

         Configuring Zope installation
         
         Testing for an acceptable Python interpreter...
         
         Python version 2.4.3 found at /usr/bin/python
         
         The optimum Python version (2.4.3) was found at /usr/bin/python.

     In case of errors, you might provide a --with-python option.

     The Zope package is now configured and ready to be built. We
     start the process by doing:

       ::
 
         ~/zope/build/Zope-2.9.8-final$ make

     and, if everything worked fine:

       ::

         ~/zope/build/Zope-2.9.8-final$ make install

     The first step, the call of 'make', takes the biggest amount of
     time and is the crucial part of the whole installation process.

     The make command may raise some compiler warnings (complaining
     about eventually uninitialized variables), especially, if using
     the up-to-date version of gcc. You can safely ignore them.

     But if you get real error messages (not only warnings) something is
     seriously wrong and you have to resolve this problems before
     proceeding. In most cases it is a matter of (not) installed Python/gcc
     packages and depends on your system. There is a very high
     probability, that you can find some hints regarding your issues
     using Google or other internet ressources.

     If no serious errors occured: congratulations! You finally
     installed your first Zope.

     If you are short of disk space, you can now safely remove the
     complete directory tree in the 'build/' directory. All needed
     software is now installed in the base/ directory.


  5. *Install a Zope instance*

     We can now change to our freshly created Zope installation:

       ::

         ~$ cd /home/user/zope/base/2_9_8

     Instead of '2_9_8' you must use the name given to the prefix
     option of the 'configure'-script above.

     Here you can find some subdirectories of which for now only the
     bin-directory is of interest:

       ::

         ~/zope/base/2_9_8$ ls
         bin  include  lib  skel  zopeskel
         ~/zope/base/2_9_8$ cd bin
         ~/zope/base/2_9_8/bin$ ls
         analyze.py        fstail.py           requestprofiler.py   zeoctl.py
         checkbtrees.py    fstest.py           runzeo.py            zeopack.py
         check_catalog.py  load_site.py        simul.py             zeopasswd.py
         compilezpy.py     migrate.py          space.py             zeoqueue.py
         copyzopeskel.py   mkzeoinstance.py    stats.py             zeoreplay.py
         copyzopeskel.pyc  mkzeoinst.py        test.py              zeoserverlog.py
         decompilezpy.py   mkzopeinstance.py   timeout.py           zeoup.py
         fsdump.py         netspace.py         zconfig              zodbload.py
         fsoids.py         parsezeolog.py      zconfig_schema2html  zopetest
         fsrefs.py         reindex_catalog.py  zdctl.py             zpasswd.py
         fsstats.py        repozo.py           zdrun.py

    Almost all of these files are executables, i.e. programs, you
    might need in your further work with Zope. Most Zope
    administrators, however, know only the script 'mkzopeinstance.py',
    which creates a new Zope instance. We will use it too. First we
    call it with the '--help' option, to see, what the script can do
    for us:

      ::

        ~/zope/base/2_9_8/bin$ ./mkzopeinstance.py --help
        mkzopeinstance.py:  Create a Zope instance home.

        usage:  mkzopeinstance.py [options]

        Options:
         -h/--help -- print this help text
         -d/--dir  -- the dir in which the instance home should be created
         -u/--user NAME:PASSWORD -- set the user name and password of the initial user
         -s/--skelsrc -- the dir from which skeleton files should be copied

        When run without arguments, this script will ask for the information necessary
        to create a Zope instance home.

    Note: On UN*X systems the '--help' switch is very common. Most programs
    support it.

    The help message displayed tells us, that we can name a directory
    to specify, where the instance should be created and a
    username/password pair for the initial login. That is, what we are
    going to do. As path for the instance we choose a (yet not
    existing) directory in the 'instances'-directory, say
    'myinstance1'. The user/password values for our first local tries
    can be kept simple:

      ::

        ~/zope/base/2_9_8/bin$ ./mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret

    This takes only about one second. If you do not give a username
    and password via parameters, you will be prompted for the data.

  6. *Configure and start your new instance*

    Change to the instances directory, to see, whether your new Zope
    instance was created:

      ::

        ~$ cd /home/user/zope/instances
        ~/zope/instances$ ls
        myinstance1

    Okay, the instance exists, so go in and have a look:

      ::

        ~/zope/instances$ cd myinstance1
        ~/zope/instances/myinstance1$ ls
        bin  etc  Extensions  import  inituser  lib  log  Products  README.txt  var

    Here we see the main directories for the further work with
    Zope. The most important directories:

      * *bin -- Executables to start/stop your instance*

        This directory contains the programs to start or stop your
        Zope instance. You can do much more with them, but we refer to
        the extended possibilities later on.

      * *etc -- Configuration of your instance*

        This directory holds the important configuration file of your
        Zope instance. Chances are, that you do not need to change the
        default configuration, but we will take a look into it anyway.

      * *log -- Logfiles of your instance*

        Here you can find the logs of your instance. Namely the access
        logfile 'Z2.log' and an error log called 'event.log'. The
        event log saves all Zope specific events, not only errors.

      * *Products -- 3rd-party products repository*

        Here can install all products, like CPS or the WAeUP SRP
        product. They are generally installed on a per-instance basis.

      * *var -- The data directory*

        In this directory will Zope save all runtime information,
        i.e. the Z Object DataBase (ZODB) and other temporary
        data. The ZODB will be held in a file called Data.fs, which
        contains all the data you entered into the running Zope
        system. If it gets corrupted, the whole instance is lost. In
        special cases (ZEO setup etc.) the Data.fs can be shared
        amongst several Zope instances and reside at another place.

    Before starting the instance, first have a look at the
    configuration file 'zope.conf' which can be found in the
    etc-directory of your instance.

    With growing version numbers of Zope also the Zope configuration
    file grows larger and larger. For version 2.9.8 there are too many
    options available in zope.conf, to discuss every single option
    herein.

    One option, however, is of special interest: the port number,
    where the Zope instance will listen to requests.

    'zope.conf' is a simple plain text file, which you can edit with
    any text editor (please do not use something like OpenOffice or
    Word to edit a plain text file: it won't be plain text any
    more). To view its content you can use the command 'less' on
    UN*X.

    In the zope.conf you will find (near the end of file) a section
    called 'http-server', which looks like this:

      ::

        #
        #     An HTTP server starts on port 8080.

        <http-server>
        # valid keys are "address" and "force-connection-close"
          address 8080
          # force-connection-close on
        </http-server>

    This means, Zope will listen on port 8080. This is okay, if there
    is no other process still listening on port 8080 (note for geeks:
    you can use the 'netstat' tool to check, which ports are already
    in use). But if you want to run several Zope instances in
    parallel, you must set the listening port to another value.

    We assume, port 8080 is not in use and simply start the Zope
    instance in the foreground for the first time:

      ::

        ~/zope/instances/myinstance1$ ./bin/runzope

    You will get some DeprecationWarnings and a message about a
    installed sighandler. This means, Zope has started and you should
    be able to use your Browser and browse to

      http://localhost:8080/

    Note the portnumber in the URL:

      .. image:: ./snapshot1.png

    If you can see the Zope Quick Start screen, everything is fine and
    you can stop the Zope instance on the console by typing CTRL-C.

    We used the 'runzope' script to start Zope in the foreground. This
    is a recommended way to start freshly created instances, because
    problems occurring during the startup process will be displayed
    directly on the screen (in the shell).

    For long-term use this is not an option, because you want to run
    Zope as a server, which runs in the background and continues to
    run, when you log out. To start Zope in background use the
    'zopectl' command. It requires a parameter, which specifies the
    action to be taken:

      ::

        zopectl start|stop|restart

    There are other possible actions as well, but for the beginning we
    start with 'start':

      ::

        ~/zope/instances/myinstance1$ ./bin/zopectl start
        . . . daemon process started, pid=457

    You now have Zope running in regular mode. Check it by visiting
    the Quick Start Page.

    If everything went fine, you can see the startup messages in the
    logfiles in the log directory of your instance.

    You can also enter the Zope Management Interface (ZMI), by adding
    '/manage' to the URL:

      http://localhost:8080/manage

    This requires to enter the credentials, you gave during
    installation of the instance.

      .. image:: ./snapshot2.png

    After successfull authorization you should be able to see the ZMI:

      .. image:: ./snapshot3.png

That's it. You installed Zope successfully. Congratulations! To
stop your running instance, you can go to the control panel in the
ZMI and shutdown by mouse-click, or, on the commandline, do

  ::

    ~/zope/instances/myinstance1$ ./bin/zopectl stop

You can play a bit with your instance and then try to do the other
steps to run a fully working version of the WAeUP SRP.

*Have fun!*

*Uli Fouquet*

(updated in 2009-01 to Zope 2.9.8, as used by current WAeUP portals, by Hraban)