Merge pull request #32 from zopefoundation/20-document_wsgi_publisher

Document running under WSGI server.

.gitignore

@@ -15,4 +15,4 @@ eggs/
 include/
 lib/
 parts/
-doc/.build/
+doc/_build/

.travis.yml

@@ -6,7 +6,7 @@ python:
 
 notifications:
   email:
-    - hanno@hannosch.eu
+    - tseaver@palladion.com
 
 install:
     - python bootstrap.py

doc/CHANGES.rst

@@ -8,6 +8,9 @@ http://docs.zope.org/zope2/
 2.13.23 (unreleased)
 --------------------
 
+- Document running Zope as a WSGI application.  See
+  https://github.com/zopefoundation/Zope/issues/30
+
 - LP #1465432:  Ensure that WSGIPublisher starts / ends interaction at
   request boundaries (analogous to ZPublisher).  Backport from master.
 

doc/INSTALL.rst → doc/INSTALL-buildout.rst

-Installing and Zope with ``zc.buildout``
-========================================
+Installing Zope with ``zc.buildout``
+====================================
 
 .. highlight:: bash
 

doc/INSTALL-virtualenv.rst

+Installing Zope with ``virtualenv``
+===================================
+
+.. highlight:: bash
+
+This document describes how to install Zope into a ``virtualenv``.
+
+
+Create a Virtual Environment
+----------------------------
+
+.. code-block:: sh
+
+   $ /opt/Python-2.7.9/bin/virtualenv z213
+   New python executable in z213/bin/python
+   Installing setuptools, pip, wheel...done.
+   $ cd z213
+
+
+Install the Zope2 2.13.22 Software Packages
+-------------------------------------------
+
+.. code-block:: sh
+
+   $ bin/pip install \
+    --trusted-host download.zope.org \
+    --index http://download.zope.org/Zope2/index/2.13.22/ Zope2
+   Collecting Zope2
+   ...
+   Successfully installed ...
+
+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:
+
+.. code-block:: sh
+
+  $ bin/mkzopeinstance
+
+You can specify the Python interpreter to use for the instance
+explicitly:
+
+.. code-block:: sh
+
+  $ bin/mkzopeinstance --python=bin/python
+
+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:
+
+.. code-block:: sh
+
+   $ bin/mkzopeinstance --help
+
+Using the ``virtualenv`` as the Zope Instance
+---------------------------------------------
+
+You can choose to use the ``virtualenv`` as your Zope instance:
+
+.. code-block:: sh
+
+   $ bin/mkzopeinstance -d .
+
+In this case, the instance files will be located in the
+subdirectories of the ``virtualenv``:
+
+- ``etc/`` will hold the configuration files.
+- ``log/`` will hold the log files.
+- ``var/`` will hold the database files.

doc/Makefile

@@ -9,7 +9,7 @@ PAPER         =
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
@@ -24,52 +24,52 @@ help:
 	@echo "  linkcheck to check all external links for integrity"
 
 clean:
-	-rm -rf .build/*
+	-rm -rf _build/*
 
 html:
-	mkdir -p .build/html .build/doctrees
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+	mkdir -p _build/html _build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
 	@echo
-	@echo "Build finished. The HTML pages are in .build/html."
+	@echo "Build finished. The HTML pages are in _build/html."
 
 pickle:
-	mkdir -p .build/pickle .build/doctrees
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+	mkdir -p _build/pickle _build/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 web: pickle
 
 json:
-	mkdir -p .build/json .build/doctrees
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json
+	mkdir -p _build/json _build/doctrees
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	mkdir -p .build/htmlhelp .build/doctrees
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+	mkdir -p _build/htmlhelp _build/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in .build/htmlhelp."
+	      ".hhp project file in _build/htmlhelp."
 
 latex:
-	mkdir -p .build/latex .build/doctrees
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+	mkdir -p _build/latex _build/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	@echo
-	@echo "Build finished; the LaTeX files are in .build/latex."
+	@echo "Build finished; the LaTeX files are in _build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
-	mkdir -p .build/changes .build/doctrees
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
+	mkdir -p _build/changes _build/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
 	@echo
-	@echo "The overview file is in .build/changes."
+	@echo "The overview file is in _build/changes."
 
 linkcheck:
-	mkdir -p .build/linkcheck .build/doctrees
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+	mkdir -p _build/linkcheck _build/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-	      "or in .build/linkcheck/output.txt."
+	      "or in _build/linkcheck/output.txt."

doc/WHATSNEW.rst

@@ -70,6 +70,8 @@ More information can be found in the detailed
 WSGI
 ----
 
+See :doc:`WSGI`.
+
 This Zope release comes with native WSGI support. First pioneered in the
 repoze.zope2 project, this capability finally found its way back into the core
 and obsoletes the externally managed project. With WSGI Zope 2 can natively talk
@@ -79,13 +81,11 @@ factoring out capabilities into WSGI endware. It's expected that this new
 deployment model will over time become the default and the old ZServer
 implementation will be deprecated. There's no concrete timeline for this yet.
 
-NOTE: There's no setup documentation nor streamlined instance creation logic
-for a WSGI setup yet. You are expected to know exactly what you are doing if
-you are trying to use this feature.
+.. note::
 
-Due to the way logic is split out into WSGI middleware, some of the
-`ZPublisher.pubevents` aren't emitted by the WSGI publisher. These are:
-`PubSuccess`, `PubFailure`, `PubBeforeCommit` and `PubBeforeAbort`.
+   Due to the way logic is split out into WSGI middleware, some of the
+   `ZPublisher.pubevents` aren't emitted by the WSGI publisher. These are:
+   `PubSuccess`, `PubFailure`, `PubBeforeCommit` and `PubBeforeAbort`.
 
 
 Zope Toolkit

doc/WSGI.rst

+Running Zope2 as a WSGI Application
+===================================
+
+
+This document assumes you have installed Zope into a ``virtualenv`` (see
+:doc:`INSTALL-virtualenv`).
+
+Install the Supporting Software
+-------------------------------
+
+To run as a WSGI application, you need to install some additional software.
+
+.. code-block:: sh
+
+   $ bin/pip install \
+    --trusted-host download.zope.org \
+    --index http://download.zope.org/Zope2/index/2.13.22/ \
+    repoze.who repoze.tm2 repoze.retry Paste PasteDeploy PasteScript
+   Collecting repoze.who
+   ...
+   Successfully installed Paste-1.7.5.1 PasteDeploy-1.3.4 PasteScript-1.7.5 repoze.retry-1.2 repoze.tm2-1.0 repoze.who-2.0
+
+
+Update the Zope Application Configuration
+-----------------------------------------
+
+The generated ``etc/zope.conf`` file assumes that Zope will be running
+using the built-in ``ZServer``.
+
+.. code-block:: sh
+
+   $ vim etc/zope.conf
+
+Update the contents as follows.
+
+.. code-block:: apacheconf
+
+   %define INSTANCE /path/to/virtualenv
+   instancehome $INSTANCE
+
+.. note::
+   
+   The ``%define instance /path/to/virtualenv`` element must
+   point to the environment:  there is no "relative to this file" support
+   built in.
+
+Set up logging for the application.
+
+.. code-block:: apacheconf
+
+   <eventlog>
+     level info
+     <logfile>
+       path $INSTANCE/log/event.log
+       level info
+     </logfile>
+   </eventlog>
+
+   <logger access>
+     level WARN
+     <logfile>
+       path $INSTANCE/log/Z2.log
+       format %(message)s
+     </logfile>
+   </logger>
+
+Configure the database (note that you could use ``ZEO`` or ``Relstorage``
+rather than a bare ``FileStorage``):
+
+.. code-block:: apacheconf
+
+   <zodb_db main>
+       # Main FileStorage database
+       <filestorage>
+         # See .../ZODB/component.xml for directives (sectiontype
+         # "filestorage").
+         path $INSTANCE/var/Data.fs
+       </filestorage>
+       mount-point /
+   </zodb_db>
+
+   <zodb_db temporary>
+       # Temporary storage database (for sessions)
+       <temporarystorage>
+         name temporary storage for sessioning
+       </temporarystorage>
+       mount-point /temp_folder
+       container-class Products.TemporaryFolder.TemporaryContainer
+   </zodb_db>
+
+Because we will be running a separately-configured WSGI server, remove any
+``<http-server>`` configuration from the file.
+
+Create the WSGI Server Configuration
+------------------------------------
+
+.. code-block:: sh
+
+   $ vim etc/zope.wsgi
+
+
+First, configure the "application" endpoint for Zope:
+
+.. code-block:: ini
+
+   [app:zope]
+   use = egg:Zope2#main
+   zope_conf = %(here)s/zope.conf
+
+
+Next, set up the WSGI middleware pipeline:
+
+.. code-block:: ini
+
+   [pipeline:main]
+   pipeline =
+       egg:paste#evalerror
+       egg:repoze.retry#retry
+       egg:repoze.tm2#tm
+       zope
+
+The middleware layers are "wrapped" around the application endpoint as follows:
+
+- ``paste#evalerror`` is debugging middleware, which shows tracebacks for
+  errors raised from the application.  It should **not** be configured for
+  production use.
+
+- ``repoze.retry#retry`` is middleware which retries requests when retriable
+  exceptions are raised.  By default, it retries 3 times, and only for
+  requests which raise ``ZODB.ConflictError``.  See
+  http://repozeretry.rtfd.org/ for details on configuring it otherwise.
+
+- ``repoze.tm2#tm`` is middleware which begins a new transaction for each
+  request, and then either aborts the transaction (if the request raises an
+  exception) or commits it (if not).  See
+  http://repozetm2.rtfd.org/ for details on configuring it.
+
+Finally, configure the WSGI server:
+
+.. code-block:: ini
+
+   [server:main]
+   use = egg:paste#http
+   host = localhost
+   port = 8080
+
+.. note::
+   
+   Any server conforming to PEP 333/3333 should work, although the parameters
+   could change.
+
+
+Set up the Admin User
+---------------------
+
+Before starting the WSGI server, run the ``addzope2user`` script to configure
+the administrative user.
+
+.. code-block:: sh
+
+   $ bin/addzope2user admin <yourpasswordhere>
+   No handlers could be found for logger "ZODB.FileStorage"
+   User admin created.
+
+
+Start the WSGI Server
+---------------------
+
+.. code-block:: sh
+
+   $ bin/paster serve etc/zope.wsgi 
+   Starting server in PID 24934.
+   serving on http://127.0.0.1:8080
+
+Running Other Applications in the same WSGI Server Process
+----------------------------------------------------------
+
+You can use any of the normal ``Paste`` WSGI features to combine Zope and
+other WSGI applications inside the same server process.  E.g., the following
+configuration uses the
+`composite application <http://pythonpaste.org/deploy/#composite-applications>`_
+support offered by ``PasteDeploy`` to host Zope at the ``/`` prefix,
+with static files served from disk at ``/static``:
+
+.. code-block:: ini
+
+   [app:zope-app]
+   use = egg:Zope2#main
+   zope_conf = %(here)s/zope.conf
+
+   [pipeline:zope-pipeline]
+   pipeline =
+       egg:paste#evalerror
+       egg:repoze.retry#retry
+       egg:repoze.tm2#tm
+       zope
+
+   [app:static]
+   use = egg:Paste#static
+   document_root = %(here)s/static
+
+   [composite:main]
+   use = egg:Paste#urlmap
+   / = zope-pipeline
+   /static = static

doc/_static/placeholder.txt

+Preserve "empty" directory under git.

doc/_templates/placeholder.txt

+Preserve "empty" directory under git.

doc/conf.py

@@ -29,7 +29,7 @@ import sys, os
 extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -115,7 +115,7 @@ html_style = 'default.css'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/index.rst

@@ -12,13 +12,15 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   WHATSNEW.rst
-   INSTALL.rst
-   operation.rst
-   USERS.rst
-   SECURITY.rst
-   SETUID.rst
-   SIGNALS.rst
-   DEBUGGING.rst
-   CHANGES.rst
+   WHATSNEW
+   INSTALL-buildout
+   INSTALL-virtualenv
+   operation
+   WSGI
+   USERS
+   SECURITY
+   SETUID
+   SIGNALS
+   DEBUGGING
+   CHANGES
 

doc/operation.rst

@@ -5,8 +5,8 @@ Configuring and Running Zope
 
 
 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.
+:doc:`INSTALL-buildout` and :doc:`INSTALL-virtualenv`), the end result is
+configured and operated the same way.
 
 
 Configuring Zope