Building and installing Zope from source
----------------------------------------

  Welcome to Zope!  This document describes building and installing
  Zope on UNIX and Linux.
  
  See WINDOWS.txt for information about Windows.  See the PLATFORMS
  directory for notes about various other platforms.

System requirements when building from source

   bash or another Bourne shell variant
   Python 2.3.5 or later installed somewhere in the system PATH
   (Note: Python 2.4 is officially *not* supported because there has not
   been a security audit for Python 2.4 and Zope 2 so far. If you use
   Python 2.4 with Zope then you use it at your own risk from the security
   perspective).
   GNU make
   A C compiler (gcc recommended)

Recommendations

  - You are recommended to build and install Zope as a non-root user.

Building Zope

  To build Zope, run the conventional UNIX build sequence from within
  the Zope source tree::

    ./configure --prefix=/where/to/install/zope
    make

  If you do not specify a '--prefix' option, during a later step, Zope
  will be installed into a default location.

  If the configure script cannot find a suitable Python interpreter
  for use with Zope, it will complain with an informative error
  message.  If this happens, you may use the '--with-python'
  command-line option to 'configure' to specify which Python
  interpreter to use.  Run './configure --help' to see other
  command-line options available via the configure script.

  Optional:  Building and Installing Zope 'In-Place'

    Older versions of Zope were typically run directly from the
    'source' directory itself.  This is useful for development
    purposes.  You can regain that behavior by performing the
    following sequence of commands within a Zope source directory:

      ./configure
      make instance

    This command also creates an administrative user with the
    specified username and password.

    WARNING: "make instance" doesn't work on FreeBSD 5.0 and
    presumably other platforms. You should either use GNU make
    (gmake instance), or use "make install" instead.

    Making an "In-Place" instance builds the binary files and creates
    the files necessary for a Zope instance to be run directly
    within the build directory (e.g. 'in-place').  You may start
    Zope by running::

      ./bin/runzope

  Optional:  Building Zope Using The "Clean-Source-Tree" Method

    You can run the 'configure' command from outside of the Zope
    source tree.  If you do so, the makefile will be written to your
    current directory.  The files generated by the build process (via
    'make') will be written to the directory from which you run
    'configure'.  You can then use 'make install' to install these
    files to their canonical locations.  This feature is to support
    source locations which are not writable.

Installing Zope

  To install Zope to the place you've specified via the '--prefix'
  option (or to the default location if you didn't specify a prefix),
  type::

    make install

Creating a Zope Instance Home

  Once you've performed the install step, to begin actually using
  Zope, you will need to create an "instance home", which is a
  directory that contains configuration and data for a Zope server
  process.  The instance home is created using the 'mkzopeinstance.py'
  script::

    /where/to/install/zope/bin/mkzopeinstance.py

  You will be asked to provide a user name and password for an
  administrator's account during 'mkzopeinstance'.  Command-line
  options to 'mkzopeinstance' are available, and can be investigated
  by running 'mkzopeinstance.py --help'.

Starting Zope

  Once an instance home has been created, the Zope server can now be
  started using this command:

    /location/of/zope/instance/bin/runzope

  If you get errors indicating that addresses are in use, then you
  will have to supply arguments to runzope to change the ports used
  for HTTP or FTP. The default HTTP and FTP ports used by Zope are
  8080 and 8021 respectively. You can change the ports used by
  specifying the "port-base" parameter to runzope.  For example, to
  run Zope on ports 9080 and 9021::

    ./bin/runzope -X port-base=1000

  There is also an interactive Zope command shell named 'zopectl' that
  may be invoked by running 'bin/zopectl'.  By default, 'zopectl
  start' will start a background process that manages Zope and
  'zopectl stop' will stop the background process.

Logging In To Zope

  Once you've started Zope, you can then connect to the Zope webserver
  by directing your browser to::

     http://yourhost:8080/manage

  .. where 'yourhost' is the DNS name or IP address of the machine
  running Zope.  If you changed the HTTP port as described, use a port
  number of 8080 + the port-base value.

  You will be prompted for a user name and password. Use the user name
  and password you provided in response to the prompts issued during
  the "make instance" process.

  Now you're off and running! You should be looking at the Zope
  management screen which is divided into two frames. On the left you
  can navigate between Zope objects and on the right you can edit them
  by selecting different management functions with the tabs at the top
  of the frame.

  If you haven't used Zope before, you should head to the Zope web
  site and read some documentation. The Zope Book is a good place to
  start. You can access the Zope Book at:

    http://www.zope.org/Documentation/Books/ZopeBook

Integrating Zope With An Existing Webserver

  Zope doesn't require any existing webserver to run, but you can
  integrate it with other webservers as necessary.  See the
  WEBSERVERS.txt file for more information about configuring Zope with
  an existing web server.  There is also information about integrating
  Zope with existing webservers on the Zope.org website.

Troubleshooting

  - This version of Zope requires Python 2.3.4 or better.

  - The Python you run Zope with *must* have threads compiled in,
    which is the case for a vanilla build.  Warning: Zope will not run
    with a Python version that uses libpth.  You *must* use
    libpthread.

  - To build Python extensions you need to have Python configuration
    information available. If your Python comes from an RPM you may
    need the python-devel (or python-dev) package installed too. If
    you built Python from source all the configuration information
    should already be available.

  - See CHANGES.txt for important notes on this version of Zope.


