Installing and configuring a Grok site under Repoze

Creating the sandbox

Then we create the actual sandbox. Replace ${sandbox} by a directory where you would like to install the Grok sandbox:

$ virtualenv --no-site-packages ${sandbox}
$ cd ${sandbox}
$ . bin/activate

The --no-site-packages option ensures that the new Python installation does not inherit any packages from the normal installation.

Installing repoze.grok

After this is done, we finally install Grok using a specially packaged egg from the repoze.org repository. The next step installs Grok into the sandbox. Normally you should only execute the following:

$ easy_install -i http://dist.repoze.org/grok/latest/simple repoze.grok

But repoze.grok 0.1.6 ships with grok 0.11, not the latest version. So instead you get the repoze.grok in editable mode and edit the setup.py to include grok 0.13 (or the latest):

$ easy_install -b . -e -i http://dist.repoze.org/grok/latest/simple repoze.grok
$ cd repoze.grok
$ vi setup.py  # set GROK_VERSION = '0.13'
$ vi setup.cfg # comment easy_install section
$ python setup.py develop
$ cd ..

This command was run using my regular user account and created a grok directory which is actually the Repoze sandbox. The repoze.grok egg that installs this also installs a few sample configuration files, which may be used almost "as is" to run the new site.

The last thing you need to do is to create the Grok instance:

$ mkgrokinstance .

This creates all the required configuration files in etc, directories (var and log) for a Zope instance and a 'bin/grok.wsgi' script for use with mod_wsgi. The most important files are located on the etc directory of the sandbox:

• 'grok.ini', a Paste configuration file used to establish the Paste (WSGI) pipeline which will be used 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.

Configure a password for the Manager, first copy the sample-users.zcml file:

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

and change the password in etc/users.zcml.

Now all you need to do is copy the apache2.conf file from the etc directory in your sandbox into your Apache configuration (with the appropiate edits for your site, of course). This file contains an almost identical configuration to the one shown on the repoze.org site, on the deployment page. Copy it in your /etc/apache2/sites-available/ directory:

$ sudo cp etc/apache2.conf /etc/apache2/sites-available/grok

You can give the name you want for the file, here it's called grok.

Configuration of your grok site

WSGIPythonHome ${sandbox}
WSGIDaemonProcess grok user=${youruser} group=${youruser} threads=1 processes=4 maximum-requests=10000 python-path=${sandbox}/lib/python2.4/site-packages
# python-eggs=/tmp/python-eggs
# please remove processes=4 if you don't use a ZEO server!

<VirtualHost *>
  ServerName my.machine.local
  WSGIScriptAlias /site ${sandbox}/bin/grok.wsgi
  WSGIProcessGroup grok
  WSGIPassAuthorization On
  WSGIReloadMechanism Process
  SetEnv HTTP_X_VHM_HOST http://my.machine.local/site
  SetEnv PASTE_CONFIG ${sandbox}/etc/grok.ini
</VirtualHost>

Configuring ZEO server

Since this configuration is intended for production use, you will also need to setup a ZEO server and configure the zope process to connect to it.

The ZEO server is already configured in etc/zeo.conf and you have the two scripts bin/zeoctl bin/runzeo generated as entry_point at the installation of ZODB3 egg.

Note: The bin/mkzeoinst . command seems to be an old thing. It will generate bin/zeoctl bin/runzeo scripts and etc/zeo.conf only if they don't exist. If you remove these files and execute the command, you will have an old zeo.conf where it search zdaemon/zdrun.py in ZODB3 egg instead of zdaemon egg. The two scripts generated execute the same thing as entry_point generated but include already the "-C etc/zeo.conf" option. So don't execute this command, you have already all needed files.

You have to configure ZEO client in the zope.conf file. Here is an example:

<zodb_db main>
  cache-size 10000
  <zeoclient>
      server localhost:8100
      storage 1
      cache-size 100MB
      name zeostorage
      var $INSTANCE/var
  </zeoclient>
  mount-point /
</zodb_db>

Normally, you have to uncomment the existing section in zope.conf file and comment the other zodb section.

Launch the server

To run Grok behind mod_wsgi, you have to start the ZEO and restart Apache. First start the the ZEO server (before reloading apache2):

$ bin/zeoctl -C etc/zeo.conf start
. daemon process started, pid=7538

But zeo dies and I don't know why. log/zeo.log gives me:

2008-07-28T15:32:06 INFO root daemon manager started
2008-07-28T15:32:06 INFO root spawned process pid=7538
2008-07-28T15:32:06 INFO root sleep 1 to avoid rapid restarts
2008-07-28T15:32:06 INFO root pid 7538: exit status 2; exiting now

Actually only this command works:

$ bin/runzeo -C etc/zeo.conf

You may prefer in this case to deactivate the ZEO server by reverting the change in zope.conf and removing processes attribute in the WSGIDaemonProcess directive.

The first time, enable your site and reload apache2:

$ sudo a2ensite grok
$ sudo /etc/init.d/apache2 reload

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

To stop your site:

$ sudo a2dissite grok
$ sudo /etc/init.d/apache2 reload

To reload your site:

$ touch bin/grok.wsgi

# /etc/init.d/apache2 reload
# /etc/init.d/apache2 stop

$ bin/paster serve etc/grok.ini

$ bin/paster serve --reload etc/grok.ini

Serve a grok project

You may create a new grok project by invoking:

$ easy_install -U grokproject # to be sure we have the latest version (here 0.8)
$ grokproject --run-buildout=no helloworld
$ cd helloworld
$ python2.4 setup.py develop

Be careful, your virtual environment have to be activated to use the good python. The helloworld/buildout.cfg and helloworld/bootstrap.py files will not be used.

Then create a ZCML slug, a file ${sandbox}/etc/grok-apps/helloworld-configure.zcml with only one line:

<include package="helloworld" />

You have to reload your site by touching grok.wsgi. You Grok application is ready to run under mod_wsgi, and perhaps be combined with other Python WSGI applications on the same site.

To use an existing grok project, enter in your project, develop the egg and create a ZCML slug like above.

Troubleshooting

Further readings

• http://repoze.org/quickstart.html
• http://repoze.org/devdep.html
• http://www.modwsgi.org