[Zope-Checkins] SVN: Zope/branches/2.12/doc/ Merge 'tseaver-clarify_install_docs' branch.
Tres Seaver
tseaver at palladion.com
Mon Mar 8 17:54:01 EST 2010
Log message for revision 109858:
Merge 'tseaver-clarify_install_docs' branch.
Changed:
A Zope/branches/2.12/doc/INSTALL-buildout.rst
U Zope/branches/2.12/doc/INSTALL.rst
U Zope/branches/2.12/doc/index.rst
A Zope/branches/2.12/doc/operation.rst
-=-
Copied: Zope/branches/2.12/doc/INSTALL-buildout.rst (from rev 109567, Zope/branches/tseaver-clarify_install_docs/doc/INSTALL-buildout.rst)
===================================================================
--- Zope/branches/2.12/doc/INSTALL-buildout.rst (rev 0)
+++ Zope/branches/2.12/doc/INSTALL-buildout.rst 2010-03-08 22:54:01 UTC (rev 109858)
@@ -0,0 +1,181 @@
+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``, ``logs`` 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
+
+.. 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.
+
+
+After installation, refer to :doc:`operation` for documentation on
+configuring and running Zope.
Modified: Zope/branches/2.12/doc/INSTALL.rst
===================================================================
--- Zope/branches/2.12/doc/INSTALL.rst 2010-03-08 22:49:05 UTC (rev 109857)
+++ Zope/branches/2.12/doc/INSTALL.rst 2010-03-08 22:54:01 UTC (rev 109858)
@@ -1,13 +1,13 @@
-============================
-Building and Installing Zope
-============================
+Installing Zope
+===============
.. highlight:: bash
This document descibes how to get going with Zope.
+
Prerequisites
-=============
+-------------
In order to use Zope, you must have the following pre-requisites
available:
@@ -31,82 +31,33 @@
__ https://sourceforge.net/projects/pywin32/
+
Installing Zope
-===============
+---------------
-Unless using buildout to build a zope instance as described
-:ref:`below <buildout-instances>`, you will need to install Zope
-separately. If you want to create a buildout-based Zope instance,
-please skip directly to that section.
+The recommended way to install Zope is within a virtualized Python environment
+using ``virtualenv`` as follows::
-Installing Zope using virtualenv
---------------------------------
-
-Zope can be installed within a virtualized Python environment using
-``virtualenv`` as follows::
-
$ virtualenv --no-site-packages my_zope
$ cd my_zope
- $ source bin/activate
$ bin/easy_install -i http://download.zope.org/Zope2/index/<Zope version> Zope2
-Using ``virtualenv`` is **highly recommended**. Otherwise, you may encounter
-unexpected conflicts with packages that have already been installed.
+If you don't already have ``virtualenv`` installed on your system, download
+the latest release from the `virtualenv PyPI page
+<http://pypi.python.org/pypi/virtaulenv>`_, unpack it, and install it, e.g.::
-Once you've installed Zope, you'll need to :ref:`create an instance <classic-instances>`.
+ $ wget http://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.4.5.tar.gz
+ $ tar xzf virtualenv-1.4.5.tar.gz
+ $ cd virtuaenv-1.4.5
+ $ /path/to/python2.6 setup.py install
-Installing Zope using zc.buildout
----------------------------------
+If you wish to manage your Zope instance using
+buildout, please see the :doc:`INSTALL-buildout`.
-Unless you are `developing zope`__, you most likely
-want to be creating a :ref:`buildout-based Zope instance <buildout-instances>` rather
-that installing using buildout as described in this section.
-__ http://docs.zope.org/developer/
+Creating a Zope Instance
+------------------------
-However, if you really just want to create Zope instances using the
-classic ``mkzopeinstance`` but with the software installed by buildout,
-then you need to do the following:
-
-- 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-2.12.0.tar.gz
- $ cd Zope2-2.12.0
- $ /path/to/your/python bootstrap/bootstrap.py
- $ bin/buildout
-
-Once you've installed Zope, you'll need to :ref:`create an instance <classic-instances>`.
-
-Installing Zope using easy_install
-----------------------------------
-
-Zope can be installed using ``easy_install``, but it is recommended to
-use ``virtualenv`` as described above to avoid unexpected conflicts
-with other packages installed directly in your python installation.
-
-However, if you want to use easy_install globally, all you need to do
-is::
-
- $ easy_install -i http://download.zope.org/Zope2/index/<Zope version> Zope2
-
-This will create the related scripts such as ``mkzopeinstance`` within the
-scripts folder of your python installation. You can then use them to
-create instances as described below.
-
-.. _classic-instances:
-
-Creating a classic 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
@@ -114,11 +65,6 @@
$ 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::
@@ -126,225 +72,9 @@
$ bin/mkzopeinstance --help
.. note::
- The traditional "inplace" build is no longer supported. If using
- ``mkzopeinstance``, always do so outside the buildout/virtualenv
- environment. If you wish to manage your Zope instance using
- buildout, please see the section below.
+ The traditional "inplace" build is no longer supported. Always use
+ ``mkzopeinstance`` to create instances outside the virtualenv environment.
-.. _buildout-instances:
-Creating a buildout-based Zope Instance
-=======================================
-
-If you wish to use buildout to manage your Zope instance, then the
-instance is created as follows:
-
-* Create a directory for your instance. In this directory, create a
- ``etc``, ``logs`` and ``var`` subdirectories.
-
-* Download the following file into your instance directory:
-
- `http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py`__
-
- __ http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
-
-.. highlight:: none
-
-* 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.
-
-* Create a Zope configuration file starting as follows:
-
-.. topic:: etc/zope.cfg
- :class: file
-
- ::
-
- %define INSTANCE <path to your instance directory>
-
- python $INSTANCE/bin/py[.exe on Windows]
-
- instancehome $INSTANCE
-
-.. highlight:: bash
-
-* Now, run the following commands::
-
- $ /path/to/your/python bootstrap.py
- $ bin/buildout
-
- In the ``bin`` subdirectory of your instance directory, you will
- find ``runzope`` and ``zopectl`` scripts that can be used as
- normal.
-
-Using your Zope instance
-========================
-
-There are various ways to run Zope from your newly created
-instance. They are all described below.
-
-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 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 start, zope emits log messages into ./log/event.log
-You can examine it with the usual tools (cat, more, tail)
-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
-
-Configuring Zope
-================
-
-Your Zope instance is configured through a file, either found by
-default::
-
- $ /path/to/zope/instance/bin/zopectl show
- ...
- Config file: /path/to/zope/instance/etc/zope.conf
-
-or passed explicitly 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.
-
-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.
-
-If you are using a buildout-based Zope instance, you will need to
-create a user as follows::
-
- $ bin/zopectl adduser username password
-
-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.
+After installation, refer to :doc:`operation` for documentation on
+configuring and running Zope.
Modified: Zope/branches/2.12/doc/index.rst
===================================================================
--- Zope/branches/2.12/doc/index.rst 2010-03-08 22:49:05 UTC (rev 109857)
+++ Zope/branches/2.12/doc/index.rst 2010-03-08 22:54:01 UTC (rev 109858)
@@ -9,6 +9,8 @@
WHATSNEW.rst
INSTALL.rst
+ INSTALL-buildout.rst
+ operation.rst
USERS.rst
SECURITY.rst
SETUID.rst
Copied: Zope/branches/2.12/doc/operation.rst (from rev 109567, Zope/branches/tseaver-clarify_install_docs/doc/operation.rst)
===================================================================
--- Zope/branches/2.12/doc/operation.rst (rev 0)
+++ Zope/branches/2.12/doc/operation.rst 2010-03-08 22:54:01 UTC (rev 109858)
@@ -0,0 +1,155 @@
+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.
More information about the Zope-Checkins
mailing list