Overview

  repoze.grok is a decomposition of the Zope 3 appserver publication
  machinery (ZPublisher) into a WSGI application component.  It relies
  on separately-distributed middleware pieces to perform some of the
  features previously handled by zope.publisher and other parts of Zope 3.

Installing repoze.grok

  With a Python 2.4 interpreter >= 2.4.3 (**Python 2.5+ is
  unsupported**) with setuptools installed, install the 'virtualenv'
  package::

    $PYTHONHOME/bin/easy_install virtualenv

  When this is done, create a virtualenv "sandbox" to hold the
  repoze.zope2 packages and instance data:

    $PYTHONHOME/bin/virtualenv --no-site-packages /path/to/sandbox

  A directory named 'sandbox' will be created in the /path/to.
  directory.  You can use any path you like.

  After creating a virtualenv sandbox, install the 'repoze.grok egg
  into the virtualenv.

    /path/to/sandbox/bin/easy_install -i http://dist.repoze.org/grok/latest/simple repoze.grok

  After the repoze.zope2 packages are installed into the virtualenv,
  you can finally create "instance" files (config files) within the
  sandbox by running "mkgrokinstance"::

    /path/to/sandbox/bin/mkgrokinstance .

  After these steps have been performed, here's what has happened::

  - a "virtual Python" has been installed within the
    "/path/to/sandbox" directory.  Packages installed to this virtual
    Python's 'site-packages' directory will not conflict with packages
    installed into your "normal" Python's 'site-packages' directory.

  - All packages required by repoze.grok have beeen downloaded,
    compiled, and installed as Python eggs in the *virtual* Python's
    'site-packages' directory.

  - 'logs', 'var', and 'etc' directories will be created inside the
    sandbox directory.  'logs' is where Zope logs will go,
    'var' is where ZODB data files will go, 'etc' is where config
    files are placed.

  - A sample set of configuration files will be installed into the
    sandbox directory's 'etc' subdirectory.  These include::

    - 'grok.ini', a Paste configuration file used to establish the
      Paste (WSGI) pipeline which repoze.grok will use to serve up
      repoze.grok.

    - 'zope.conf', a classic Zope 2 configuration file which can be
      used to adjust Zope settings.

    - 'site.zcml', a boilerplate site.zcml that should be used to
      control ZCML processing.

    - 'sample-users.zcml', a file that declares a user, useful for
      copying into users.zcml when you want to start the site.

The Default Sandbox Configuration

  The configuration of WSGI components in the sandbox setup form a
  publishing environment in which most Zope applications should be
  able to run without modification.  Some of the jobs previously
  filled by components in Zope have been assumed by repoze and other
  WSGI middleware components:

  - The job of ZServer has been filled by the zope 3 WSGI server (via
    repoze.grok.server).

  - The job of ZPublisher object publishing has been filled by the
    object publisher in repoze.grok

  - The job of ZPublisher transaction management has been filled by
    repoze.tm middleware.

  - The Zope 2 "error_log" has been replaced with error-catching /
    error-logging middleware in Paste.

  - "access" logging can now be handled by a middleware component.

  - The job of VirtualHostMonster is now filled by repoze.vhm.

Testing repoze.grok

  To all run repoze.grok tests, after running setup.py sandbox, cd to
  the repoze.grok directory and run::

    $sandboxdir/bin/python setup.py test

Starting repoze.grok

  If you installed repoze.grok via easy_install, you will need to
  create several config files which define the server's parameters.

  You will need to create a 'users.zcml' file inside your grok
  instance's etc/ directory.  The easiest way to do this is to copy
  the sample-users.zcml file over to it.  Make sure to edit the
  derived file to change the password when you're done.

    $ cp etc/sample-users.zcml etc/users.zcml

  To start a server that serves up a demo app on port 8080, cd to the
  sandbox directory you created via "setup.py sandbox" and run::

    bin/paster serve etc/grok.ini

  When you visit http://localhost:8080/ in a browser, you should see
  the Grok Admin UI.  You should be able to log in using the admin
  login name and password (found in 'etc/site.zcml').

  You may create a new grok project by
  invoking::

   bin/grokproject --no-buildout <projectname> at the command line.

Deploying

  Due to its simplicity, the default "sandbox" server is preferred for
  development and for some forms of deployment, but to make life
  easier for people more experienced with Apache technologies than
  Zope technologies, a reasonable deployment target for repoze.grok
  is Apache via "mod_wsgi":http://code.google.com/p/modwsgi/ .
  mod_wsgi is an Apache module that allows you to run WSGI
  applications using the Apache HTTP server.

  A sample ".wsgi" deployment script (an analogue of the ones
  described in the mod_wsgi documentation) is available in the
  skel/sample_grok.wsgi file.  A sample Apache configuration which
  uses this deployment script is included in the
  skel/sample_apache2.conf file.

  It's suggested that you serve up repoze.grok with mod_wsgi in
  "daemon mode" where each if the mod_wsgi's daemon children runs a
  single-threaded Zope process.  All of the Zope processes should
  communicate with a single ZEO server on the back end.  You can run a
  ZEO server by invoking "bin/zeoctl start -C etc/zeo.conf" from
  within a Repoze sandbox.  You'll need to change etc/zope.conf,
  uncommenting the <zodb_db> section that refers to a client storage
  at that point for Zope to work.