Commit 1c7db716 authored by Tom Gross's avatar Tom Gross

Merge pull request #32 from zopefoundation/20-document_wsgi_publisher

Document running under WSGI server.
parents 778c8ff1 21d9bba5
...@@ -15,4 +15,4 @@ eggs/ ...@@ -15,4 +15,4 @@ eggs/
include/ include/
lib/ lib/
parts/ parts/
doc/.build/ doc/_build/
...@@ -6,7 +6,7 @@ python: ...@@ -6,7 +6,7 @@ python:
notifications: notifications:
email: email:
- hanno@hannosch.eu - tseaver@palladion.com
install: install:
- python bootstrap.py - python bootstrap.py
......
...@@ -8,6 +8,9 @@ http://docs.zope.org/zope2/ ...@@ -8,6 +8,9 @@ http://docs.zope.org/zope2/
2.13.23 (unreleased) 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 - LP #1465432: Ensure that WSGIPublisher starts / ends interaction at
request boundaries (analogous to ZPublisher). Backport from master. request boundaries (analogous to ZPublisher). Backport from master.
......
Installing and Zope with ``zc.buildout`` Installing Zope with ``zc.buildout``
======================================== ====================================
.. highlight:: bash .. highlight:: bash
......
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.
...@@ -9,7 +9,7 @@ PAPER = ...@@ -9,7 +9,7 @@ PAPER =
# Internal variables. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter 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 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
...@@ -24,52 +24,52 @@ help: ...@@ -24,52 +24,52 @@ help:
@echo " linkcheck to check all external links for integrity" @echo " linkcheck to check all external links for integrity"
clean: clean:
-rm -rf .build/* -rm -rf _build/*
html: html:
mkdir -p .build/html .build/doctrees mkdir -p _build/html _build/doctrees
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
@echo @echo
@echo "Build finished. The HTML pages are in .build/html." @echo "Build finished. The HTML pages are in _build/html."
pickle: pickle:
mkdir -p .build/pickle .build/doctrees mkdir -p _build/pickle _build/doctrees
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
@echo @echo
@echo "Build finished; now you can process the pickle files." @echo "Build finished; now you can process the pickle files."
web: pickle web: pickle
json: json:
mkdir -p .build/json .build/doctrees mkdir -p _build/json _build/doctrees
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) .build/json $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
@echo @echo
@echo "Build finished; now you can process the JSON files." @echo "Build finished; now you can process the JSON files."
htmlhelp: htmlhelp:
mkdir -p .build/htmlhelp .build/doctrees mkdir -p _build/htmlhelp _build/doctrees
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
@echo @echo
@echo "Build finished; now you can run HTML Help Workshop with the" \ @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: latex:
mkdir -p .build/latex .build/doctrees mkdir -p _build/latex _build/doctrees
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
@echo @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" \ @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex." "run these through (pdf)latex."
changes: changes:
mkdir -p .build/changes .build/doctrees mkdir -p _build/changes _build/doctrees
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
@echo @echo
@echo "The overview file is in .build/changes." @echo "The overview file is in _build/changes."
linkcheck: linkcheck:
mkdir -p .build/linkcheck .build/doctrees mkdir -p _build/linkcheck _build/doctrees
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
@echo @echo
@echo "Link check complete; look for any errors in the above output " \ @echo "Link check complete; look for any errors in the above output " \
"or in .build/linkcheck/output.txt." "or in _build/linkcheck/output.txt."
...@@ -70,6 +70,8 @@ More information can be found in the detailed ...@@ -70,6 +70,8 @@ More information can be found in the detailed
WSGI WSGI
---- ----
See :doc:`WSGI`.
This Zope release comes with native WSGI support. First pioneered in the 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 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 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 ...@@ -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 deployment model will over time become the default and the old ZServer
implementation will be deprecated. There's no concrete timeline for this yet. implementation will be deprecated. There's no concrete timeline for this yet.
NOTE: There's no setup documentation nor streamlined instance creation logic .. note::
for a WSGI setup yet. You are expected to know exactly what you are doing if
you are trying to use this feature.
Due to the way logic is split out into WSGI middleware, some of the 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: `ZPublisher.pubevents` aren't emitted by the WSGI publisher. These are:
`PubSuccess`, `PubFailure`, `PubBeforeCommit` and `PubBeforeAbort`. `PubSuccess`, `PubFailure`, `PubBeforeCommit` and `PubBeforeAbort`.
Zope Toolkit Zope Toolkit
......
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
Preserve "empty" directory under git.
Preserve "empty" directory under git.
...@@ -29,7 +29,7 @@ import sys, os ...@@ -29,7 +29,7 @@ import sys, os
extensions = [] extensions = []
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates'] templates_path = ['_templates']
# The suffix of source filenames. # The suffix of source filenames.
source_suffix = '.rst' source_suffix = '.rst'
...@@ -115,7 +115,7 @@ html_style = 'default.css' ...@@ -115,7 +115,7 @@ html_style = 'default.css'
# Add any paths that contain custom static files (such as style sheets) here, # 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, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # 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, # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format. # using the given strftime format.
......
...@@ -12,13 +12,15 @@ Contents: ...@@ -12,13 +12,15 @@ Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
WHATSNEW.rst WHATSNEW
INSTALL.rst INSTALL-buildout
operation.rst INSTALL-virtualenv
USERS.rst operation
SECURITY.rst WSGI
SETUID.rst USERS
SIGNALS.rst SECURITY
DEBUGGING.rst SETUID
CHANGES.rst SIGNALS
DEBUGGING
CHANGES
...@@ -5,8 +5,8 @@ Configuring and Running Zope ...@@ -5,8 +5,8 @@ Configuring and Running Zope
Whichever method you used to install Zope and create a server instance (see Whichever method you used to install Zope and create a server instance (see
:doc:`INSTALL` and :doc:`INSTALL-buildout`), the end result is configured :doc:`INSTALL-buildout` and :doc:`INSTALL-virtualenv`), the end result is
and operated the same way. configured and operated the same way.
Configuring Zope Configuring Zope
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment