Document running under WSGI server.

- Add docs for installation into a virtualenv. - Update Sphinx paths to use '_' prefix. Closes #30.
zopefoundation · Jun 20, 2015 · 6b96bc7 · 6b96bc7
1 parent 778c8ff
commit 6b96bc7
Show file tree

Hide file tree

Showing 10 changed files with 288 additions and 37 deletions.
diff --git a/.gitignore b/.gitignore
@@ -15,4 +15,4 @@ eggs/
 include/
 lib/
 parts/
-doc/.build/
+doc/_build/
diff --git a/doc/INSTALL.rst → doc/INSTALL-buildout.rst b/doc/INSTALL.rst → doc/INSTALL-buildout.rst
@@ -1,5 +1,5 @@
-Installing and Zope with ``zc.buildout``
-========================================
+Installing Zope with ``zc.buildout``
+====================================
 
 .. highlight:: bash
 

diff --git a/doc/INSTALL-virtualenv.rst b/doc/INSTALL-virtualenv.rst
@@ -0,0 +1,73 @@
+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/pythn
+
+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.
diff --git a/doc/Makefile b/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."
diff --git a/doc/WSGI.rst b/doc/WSGI.rst
@@ -0,0 +1,174 @@
+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
+
diff --git a/doc/_static/placeholder.txt b/doc/_static/placeholder.txt
@@ -0,0 +1 @@
+Preserve "empty" directory under git.
diff --git a/doc/_templates/placeholder.txt b/doc/_templates/placeholder.txt
@@ -0,0 +1 @@
+Preserve "empty" directory under git.
diff --git a/doc/conf.py b/doc/conf.py
@@ -29,7 +29,7 @@
 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 @@
 # 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.

diff --git a/doc/index.rst b/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