Merge 'tseaver-clarify_install_docs' branch.

doc/INSTALL-buildout.rst

+Installing and Zope with ``zc.buildout``
+========================================
+
+.. highlight:: bash
+
+This document descibes how to get going with Zope using ``zc.buildout``.
+
+
+About ``zc.buildout``
+---------------------
+
+`zc.buildout <http://www.buildout.org/>`_ is a powerful tool for creating
+repeatable builds of a given software configuration and environment.  The
+Zope developers use ``zc.buildout`` to develop Zope itself, as well as
+the underlying packages it uses.
+
+Prerequisites
+-------------
+
+In order to use Zope, you must have the following pre-requisites
+available: 
+
+- A supported version of Python, including the development support if
+  installed from system-level packages.  Supported versions include:
+
+  * 2.6.x
+
+- Zope needs the Python ``zlib`` module to be importable.  If you are
+  building your own Python from source, please be sure that you have the
+  headers installed which correspond to your system's ``zlib``.
+
+- A C compiler capable of building extension modules for your Python
+  (gcc recommended). This is not necessary for Windows as binary
+  releases of the parts that would need compiling are always made
+  available.
+
+- If you wish to install Zope as a Service on Windows, you will need
+  to have the `pywin32`__ package installed.
+
+  __ https://sourceforge.net/projects/pywin32/
+
+
+Installing standalone Zope using zc.buildout
+--------------------------------------------
+
+In this configuration, we use ``zc.buildout`` to install the Zope software,
+but then generate server "instances" outside the buildout environment.
+
+Installing the Zope software
+::::::::::::::::::::::::::::
+
+Installing the Zope software using ``zc.buildout`` involves the following
+steps:
+
+- Download the Zope 2 source distribution from `PyPI`__
+
+  __ http://pypi.python.org/pypi/Zope2
+
+- Bootstrap the buildout
+
+- Run the buildout
+
+On Linux, this can be done as follows::
+
+  $ wget http://pypi.python.org/packages/source/Z/Zope2/Zope2-<Zope version>.tar.gz
+  $ tar xfvz Zope2-<Zope version>.tar.gz
+  $ cd Zope2-<Zope version>
+  $ /path/to/your/python bootstrap/bootstrap.py
+  $ bin/buildout
+
+
+Creating a Zope instance
+::::::::::::::::::::::::
+
+Once you've installed Zope, you will need to create an "instance
+home". This is a directory that contains configuration and data for a
+Zope server process.  The instance home is created using the
+``mkzopeinstance`` script::
+
+  $ bin/mkzopeinstance
+
+You can specify the Python interpreter to use for the instance
+explicitly:: 
+
+  $ bin/mkzopeinstance --python=$PWD/bin/zopepy
+
+You will be asked to provide a user name and password for an
+administrator's account during ``mkzopeinstance``.  To see the available
+command-line options, run the script with the ``--help`` option::
+
+  $ bin/mkzopeinstance --help
+
+.. note::
+  The traditional "inplace" build is no longer supported. If using
+  ``mkzopeinstance``, always do so outside the buildout environment.
+
+
+Creating a buildout-based Zope instance
+---------------------------------------
+
+Rather than installing Zope separately from your instance, you may wish
+to use ``zc.buildout`` to create a self-contained environment, containing
+both the Zope software and the configuration and data for your server.
+This procedure involves the following steps:
+
+- Create the home directory for the buildout, including 
+  ``etc``, ``log`` and ``var`` subdirectories.
+
+- Fetch the buildout bootstrap script into the environment.
+
+- Create a buildout configuration as follows:
+
+.. topic:: buildout.cfg
+ :class: file
+
+ ::
+
+   [buildout]
+   parts = instance 
+   extends = http://download.zope.org/Zope2/index/<Zope version>/versions.cfg
+
+   [instance]
+   recipe = zc.recipe.egg
+   eggs = Zope2
+   interpreter = py
+   scripts = runzope zopectl
+   initialization =
+     import sys
+     sys.argv[1:1] = ['-C',r'${buildout:directory}/etc/zope.conf']
+
+This is the minimum but all the usual buildout techniques can be
+used.
+
+- Bootstrap the buildout
+
+- Run the buildout
+
+- Create a Zope configuration file.  A minimal version would be:
+
+.. topic:: etc/zope.cfg
+ :class: file
+
+ ::
+
+   %define INSTANCE <path to your instance directory>
+
+   python $INSTANCE/bin/py[.exe on Windows]
+ 
+   instancehome $INSTANCE
+
+A fully-annotated sample can be found in the Zope2 egg::
+
+   $ cat eggs/Zope2--*/Zope2/utilities/skel/etc/zope.conf.in
+
+   <rest of the stuff that goes into a zope.conf, e.g. databases and log files.>
+
+.. highlight:: bash
+
+An example session::
+
+   $ mkdir /path/to/instance
+   $ cd /path/to/instance
+   $ mkdir etc logs var
+   $ wget http://svn.zope.org/zc.buildout/trunk/bootstrap/bootstrap.py
+   $ vi buildout.cfg
+   $ /path/to/your/python bootstrap.py
+   $ bin/buildout
+   $ cat eggs/Zope2--*/Zope2/utilities/skel/etc/zope.conf.in > etc/zope.conf
+   $ vi etc/zope.conf  # replace <<INSTANCE_HOME>> with buildout directory
+   $ bin/zopectl start
+
+In the ``bin`` subdirectory of your instance directory, you will
+find ``runzope`` and ``zopectl`` scripts that can be used as
+normal.
+
+You can use ``zopectl`` interactively as a command shell by just
+calling it without any arguments. Try ``help`` there and ``help <command>``
+to find out about additionally commands of zopectl. These commands
+also work at the command line.
+
+Note that there are there are recipes such as `plone.recipe.zope2instance
+http://pypi.python.org/pypi/plone.recipe.zope2instance`_ which can be
+used to automate this whole process.
+
+After installation, refer to :doc:`operation` for documentation on
+configuring and running Zope.

doc/index.rst

@@ -9,6 +9,8 @@ Contents:
 
    WHATSNEW.rst
    INSTALL.rst
+   INSTALL-buildout.rst
+   operation.rst
    USERS.rst
    SECURITY.rst
    SETUID.rst

doc/operation.rst

+Configuring and Running Zope
+============================
+
+.. highlight:: bash
+
+
+Whichever method you used to install Zope and create a server instance (see
+:doc:`INSTALL` and :doc:`INSTALL-buildout`), the end result is configured
+and operated the same way.
+
+
+Configuring Zope
+----------------
+
+Your instance's configuration is defined in its ``etc/zope.conf`` file.
+Unless you created the file manually, that file should contain fully-
+annotated examples of each directive.
+
+You can also pass an explicit configuration file on the commandline::
+
+  $ /path/to/zope/instance/bin/zopectl -c /tmp/other.conf show
+  ...
+  Config file:  /tmp/other.conf
+
+When starting Zope, if you see errors indicating that an address is in
+use, then you may have to change the ports Zope uses 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
+editing ./etc/zope.conf appropriately.
+
+The section in the configuration file looks like this::
+
+  <http-server>
+    # valid keys are "address" and "force-connection-close"
+    address 8080
+    # force-connection-close on
+  </http-server>
+
+The address can just be a port number as shown, or a  host:port
+pair to bind only to a specific interface.
+
+After making any changes to the configuration file, you need to restart any
+running Zope server for the affected instance before changes are in effect.
+
+
+Running Zope in the Foreground
+------------------------------
+
+To run Zope without detaching from the console, use the ``fg``
+command (short for ``foreground``)::
+
+  $ /path/to/zope/instance/bin/zopectl fg
+
+In this mode, Zope emits its log messages to the console, and does not
+detach from the terminal.
+
+
+Running Zope as a Daemon
+------------------------
+
+Once an instance home has been created, the Zope server can now be
+started using this command::
+
+  $ /path/to/zope/instance/bin/zopectl start
+
+During startup, Zope emits log messages into
+`/path/to/zope/instance/log/event.log`.  You can examine it with the usual
+tools (``cat``, ``more``, ``tail``, etc) and see if there are any errors
+preventing Zope from starting.
+
+.. highlight:: none
+.. note::
+
+  For this to work on Windows, the Zope instance must be installed as
+  a Service. This is done with::
+
+    bin\zopectl install
+
+  If you later want to remove this Service, do the following::
+
+    bin\zopectl remove
+
+  For the full list of options available for setting up Zope as a
+  Windows Service, do::
+
+    bin\zopectl install --help
+
+.. highlight:: bash
+
+
+Integrating with System Startup
+-------------------------------
+
+zopectl can be linked as rc-script in the usual start directories
+on linux or other System V unix variants.
+
+You can use ``zopectl`` interactively as a command shell by just
+calling it without any arguments. Try ``help`` there and ``help <command>``
+to find out about additionally commands of zopectl. These commands
+also work at the command line.
+
+.. note::
+
+  On Windows, a Service can be installed and set to start
+  automatically with the following:
+
+  .. code-block:: none
+
+    bin\zopectl install --startup=auto
+
+
+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 the port
+you configured.
+
+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 Documentation section is
+a good place to start. You can access it at http://docs.zope.org/
+
+Troubleshooting
+---------------
+
+- This version of Zope requires Python 2.6.4 or better.
+  It will *not* run with Python 3.x.
+
+- 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 the :doc:`CHANGES` for important notes on this version of Zope.