[Checkins] SVN: grokproject/trunk/upgrading.txt Add draft of an upgrade-guide for grok/grokproject.
Uli Fouquet
uli at gnufix.de
Sun Sep 13 06:21:43 EDT 2009
Log message for revision 103892:
Add draft of an upgrade-guide for grok/grokproject.
Changed:
A grokproject/trunk/upgrading.txt
-=-
Added: grokproject/trunk/upgrading.txt
===================================================================
--- grokproject/trunk/upgrading.txt (rev 0)
+++ grokproject/trunk/upgrading.txt 2009-09-13 10:21:43 UTC (rev 103892)
@@ -0,0 +1,1060 @@
+
+.. ABOUT THIS DOC
+.. It's a start for an upgrade guide to all the released versions
+.. of Grok and grokproject.
+..
+.. It's work-in-progress
+..
+
+.. contents:: Detailed docs
+
+
+Upgrading generated projects
+============================
+
+There have been a lot of changes between single releases of
+`grokproject`. Here is how you can upgrade your local grok project, if
+it was generated using an older version of `grokproject`.
+
+.. note:: The version numbers mentioned herein mean the versions of
+ `grokproject`, not `grok` versions, except if explicitly
+ said so. `grokproject` versions are mainly independent from
+ the `grok` version used.
+
+Basics good to know
+-------------------
+
+We start with some basic procedures nice to know about before actually
+doing the upgrade.
+
+Which version of `grokproject` is currently installed?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Newer versions of `grokproject` (since 1.0a2) support the
+``--version`` option. Run::
+
+ $ grokproject --version
+ 1.0a4
+
+This is the version of ``grokproject`` that will be used when you
+create a new project.
+
+If your installed ``grokproject`` does not support the ``--version``
+switch (you can also run ``grokproject --help`` to see what options
+are available), then you can lookup the ``grokproject`` script
+itself. It is a little Python script and the version number is written
+down in the script itself::
+
+ $ which grokproject
+ /usr/bin/grokproject
+
+ $ less /usr/bin/grokproject
+
+will reveal what version of `grokproject` you have installed.
+
+.. _upgradetolatest:
+
+How can I upgrade to the latest ``grokproject`` version?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run::
+
+ $ easy_install -U grokproject
+
+This will fetch and install the latest version for you.
+
+.. note:: You need appropriate permissions to do so, maybe root or
+ Administrator privileges. Use virtualenv_ if this is a
+ problem for you.
+
+Upgrading the `grokproject` script will not upgrade your already
+generated projects.
+
+How can I bring the installed `grokproject` to a certain version?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to bring ``grokproject`` for instance to version 1.0a2,
+just run::
+
+ $ easy_install grokproject==1.0a2
+
+This will fetch and install `grokproject` version 1.0a2 for you. All
+versions available can be found below.
+
+.. note:: You need appropriate permissions to do so, maybe root or
+ Administrator privileges. Use virtualenv_ if this is a
+ problem for you.
+
+
+.. _pingrokversion:
+
+How can I 'pin down' a certain `grok` version with a project?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basically, you can run any `grok` version with any `grokproject`
+version.
+
+The common approach to pin a certain `grok` version down is to tell
+`buildout` to use it. This can be done by setting the version in
+`buildout.cfg`.
+
+In the ``[buildout]`` section of your `buildout.cfg` add a line like
+this::
+
+ extends = http://grok.zope.org/releaseinfo/grok-1.0a1.cfg
+
+which will read the mentioned file from the grok site and use it as a
+`versions.cfg`. Browse http://grok.zope.org/releaseinfo/ to see what
+version files are available.
+
+Alternatively you can download this file and place it in your project
+root overwriting the old `versions.cfg` file. Make sure, however, to
+copy the packages pinned down by `grokproject` itself (near bottom of
+your original `versions.cfg`) over to the new versions.cfg.
+
+
+.. _whereistheconfig:
+
+Where are the configuration files?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Location of configuration files changed with different `grokproject`
+versions.
+
+* 1.0a4, 1.0a3:
+ All configuration files are templates and can be found in
+ ``etc/``.
+
+* 1.0a2, 1.0a1:
+ All configuration files are in ``etc/``
+
+* 0.9, 0.8, 0.7, 0.6:
+ deploy.ini, debug.ini:
+ Do not exist.
+
+ site.zcml:
+ Inline in `buildout.cfg`
+
+ zdaemon.conf, zope.conf:
+ can be found in ``parts/zopectl/``
+
+* 0.4 or older:
+ deploy.ini, debug.ini:
+ Do not exist.
+
+ site.zcml:
+ Inline in `buildout.cfg`
+
+ zdaemon.conf, zope.conf:
+ can be found in ``parts/instance/``
+
+
+Which `grokproject` version was used for a **generated** project?
+-----------------------------------------------------------------
+
+If you have an already generated project you want to update, things
+are more difficult and likely to require some manual work.
+
+But before you can upgrade you have to know what version of
+`grokproject` was used when the project was created.
+
+Here is, how you can find out.
+
+1.0a4
+~~~~~
+
+Your project was generated by `grokproject` 1.0a4 if...
+
+* it contains a file ``etc/zope.conf.in`` *and*
+
+* this file contains a line saying::
+
+ site-definition ${site_zcml:output}
+
+ on top.
+
+1.0a3
+~~~~~
+
+Your project was generated by `grokproject` 1.0a3 if...
+
+* it contains a script ``zpasswd`` in ``bin/`` *and*
+
+* the ``versions.cfg`` contains also a line pinning ``grokui.admin``
+ version.
+
+1.0a2 or 1.0a1
+~~~~~~~~~~~~~~
+
+Your project was generated by `grokproject` 1.0a2 or 1.0a1 if...
+
+* it does *not* contain a script ``zpasswd`` in ``bin/`` *and*
+
+* it *does* contain a script ``paster`` in ``bin/``
+
+The changes between 1.0a1 and 1.0a2 did not touch generated projects,
+but only options of the `grokproject` script itself.
+
+0.9
+~~~
+
+Your project was generated by `grokproject` 0.9 if...
+
+* it does *not* contain a script ``paster`` in ``bin/`` *and*
+
+* it does *not* contain a line with ``lovely.recipe`` in
+ ``versions.cfg``.
+
+0.8
+~~~
+
+Your project was generated by `grokproject` 0.8 if...
+
+* it *does* contain a line with ``lovely.recipe`` in
+ ``versions.cfg`` *and*
+
+* it does contain a script ``bootstrap.py``.
+
+0.7
+~~~
+
+Your project was generated by `grokproject` 0.7 if...
+
+* it does *not* contain a script ``bootstrap.py`` *and*
+
+* the ``buildout.cfg`` contains only one ``[data]`` section.
+
+0.6
+~~~
+
+Your project was generated by `grokproject` 0.6 if...
+
+* the ``buildout.cfg`` contains two ``[data]`` sections *and*
+
+* it contains a script ``i18nextract`` in the ``bin/`` directory.
+
+0.5.1
+~~~~~
+
+Your project was generated by `grokproject` 0.5.1 if...
+
+* it does *not* contain a script ``i18nextract`` in the ``bin/``
+ directory *and*
+
+* it does *not* contain a section ``[zope3]`` in `buildout.cfg`.
+
+0.5
+~~~
+
+Your project was generated by `grokproject` 0.5 if...
+
+* it does contain a section ``[zope3]`` in `buildout.cfg` *and*
+
+* it does contain a script ``zopectl`` in the ``bin/`` directory.
+
+0.4 or older
+~~~~~~~~~~~~
+
+Your project was generated by `grokproject` 0.4 or older if...
+
+* it contains a script ``instance`` in the ``bin/`` directory.
+
+
+How can I upgrade a generated project from version X to version Y?
+------------------------------------------------------------------
+
+If you found out with which `grokproject` version your project was
+created with, you can start the real upgrading.
+
+The basic and fastest way to upgrade:
+
+Say, we have an old project ``Cave`` which was generated by
+``grokproject`` 1.0a1, we want to upgrade to 1.0a4, and the old project
+resides in ``old/Cave/``.
+
+1) Bring ``grokproject`` to the target version (`see above
+ <#upgradetolatest>`_)::
+
+ $ easy_install grokproject==1.0a4
+
+2) With this ``grokproject`` create a new project (at a new location)
+ with the *same name* as the one to upgrade. You might want to use the
+ ``--grokversion`` option to use the same ``grok`` version as your
+ old project::
+
+ $ grokproject --grokversion=1.0a3 Cave
+
+ Here we use ``grokproject`` 1.0a4 to create a project that uses
+ ``grok`` 1.0a3. Yes, this can be confusing.
+
+3) In your freshly created project remove the generated sources under
+ ``src/<projname>/``, i.e. the complete ``<projname>`` folder::
+
+ $ rm -rf Cave/src/cave
+
+4) Copy the sources of src/<projname>, i.e. the ``<projname>`` folder
+ from your old project over to the new project.
+
+ $ cp -ar old/Cave/src/cave Cave/src
+
+5) Rerun buildout in your new project::
+
+ $ cd Cave
+ $ bin/buildout
+
+ Upgrade finished.
+
+This procedere, however, might fail for certain version bumps, where
+also the mean sources (under ``src/<projname>``) have to be changed. The
+necessary additional changes are described below.
+
+In our example, for instance, we have to remove the module
+``startup.py`` from the sources.
+
+Further problems can arise, if you manually changed the main
+configuration files (i.e. in `etc/` or `parts/`, the ``buildout.cfg``
+or ``setup.py``). In this case you have to redo your changes in the
+new project.
+
+If you use version control, take care of any VC stuff copied over like
+hidden subversion directories.
+
+
+Additional Upgrade Steps (fast lane)
+------------------------------------
+
+These steps have to be performed additionally to the above mentioned
+procedure.
+
+
+Pin the `grok` version used in your old project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The freshly generated grokproject will by default use the latest grok
+version available. This might cause problems with the code of your old
+project.
+
+To use the `grok` version your old project used, lookup the `grok`
+version your old project used at top of the `versions.cfg` file of
+your old project and set this in your upgraded project as described
+`above <#pingrokversion>`_.
+
+
+Eventually remove `startup.py` from sources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your sources (i.e. the package stored in `<src/myproject>` contain
+a module `startup.py`, which was not changed since creation, you can
+safely remove it.
+
+This module was only generated for projects created with `grokproject`
+versions 1.0a1/1.0a2.
+
+
+Check parameters in configuration files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Check the parameters set in the configuration files to match the
+settings of your old project.
+
+See `Where are the configuration files?`_ to find out where the configuration
+files in your old project can be found.
+
+In you new project they can be found as templates in the `etc/`
+directory.
+
+
+Manually upgrading (detailed)
+-----------------------------
+
+If you want to perform the single changes between ``grokproject``
+releases manually, here is how to do this.
+
+
+from 1.0a3 to 1.0a4
+~~~~~~~~~~~~~~~~~~~
+
+The fastest way might be to create a new project with the same name
+with ``grokproject`` 1.0a4 and then replace the complete
+``src/<projname>`` tree of your freshly generated stuff with the
+contents of the ``src/<projectname>`` tree from your old project.
+
+If you instead want to apply all changes manually, then in your old
+project follow these steps:
+
+* remove the line pinning ``grokui.admin`` near the end of
+ ``versions.cfg``.
+
+* replace the line in section ``[handler_accesslog]`` in
+ ``etc/debug.ini.in`` starting with ``args =`` with the following
+ line::
+
+ args = (os.path.join(r'${buildout:directory}', 'parts', 'log',
+ 'access.log'), 'a')
+
+* do the same in file ``etc/deploy.ini.in``.
+
+* in ``etc/zope.conf.in`` replace::
+
+ site-definition ${buildout:directory}/etc/site.zcml
+
+ with::
+
+ site-definition ${site_zcml:output}
+
+ and replace::
+
+ path ${buildout:directory}/parts/data/Data.fs
+
+ with::
+
+ path ${data:path}
+
+* in `buildout.cfg` you might add a line to the ``[buildout]`` section
+ reading::
+
+ find-links = http://download.zope.org/distribution/
+
+ But read section `Using find-links`_ below.
+
+Rerun ``buildout`` afterwards and you should be done.
+
+
+from 1.0a2 to 1.0a3
+~~~~~~~~~~~~~~~~~~~
+
+* in ``buildout.cfg`` change the ``parts`` line near top from::
+
+ parts = eggbasket app i18n test data log
+
+ to::
+
+ parts = eggbasket app i18n test data log zpasswd
+ zope_conf site_zcml zdaemon_conf deploy_ini debug_ini
+
+* in ``buildout.cfg`` add the following sections::
+
+ # This section is named so that the zpasswd utility is
+ # called `zpasswd`
+ [zpasswd]
+ recipe = z3c.recipe.dev:script
+ eggs = <projname>
+ module = zope.app.server.zpasswd
+ method = main
+
+ [zope_conf]
+ recipe = z3c.recipe.template
+ input = etc/zope.conf.in
+ output = ${buildout:parts-directory}/etc/zope.conf
+
+ [site_zcml]
+ recipe = z3c.recipe.template
+ input = etc/site.zcml.in
+ output = ${buildout:parts-directory}/etc/site.zcml
+
+ [zdaemon_conf]
+ recipe = z3c.recipe.template
+ input = etc/zdaemon.conf.in
+ output = ${buildout:parts-directory}/etc/zdaemon.conf
+
+ [deploy_ini]
+ recipe = z3c.recipe.template
+ input = etc/deploy.ini.in
+ output = ${buildout:parts-directory}/etc/deploy.ini
+
+ [debug_ini]
+ recipe = z3c.recipe.template
+ input = etc/debug.ini.in
+ output = ${buildout:parts-directory}/etc/debug.ini
+
+ and make sure to replace ``<projname>`` in the ``[zpasswd]`` section
+ with the egg name of your project (for instance ``sample`` if your
+ project was named ``Sample``).
+
+* in ``setup.py``:
+
+ * add ``grokcore.startup`` to the required dependencies.
+
+ * in the entry-point definitions section (near end) replace::
+
+ [console_scripts]
+ <projname>-debug = <projname>.startup:interactive_debug_prompt
+ <projname>-ctl = <projname>.startup:zdaemon_controller
+ [paste.app_factory]
+ main = <projname>.startup:application_factory
+
+ with::
+
+ [console_scripts]
+ <projname>-debug = grokcore.startup:interactive_debug_prompt
+ <projname>-ctl = grokcore.startup:zdaemon_controller
+ [paste.app_factory]
+ main = grokcore.startup:application_factory
+
+ and of course fill in your real projects eggname (lowercase
+ projectname) instead of ``<projname>``.
+
+* in ``versions.cfg`` near bottom, where all `grokproject` specific
+ versions are pinned, replace::
+
+ # Here we pin the recipes used in the buildout.cfg
+ z3c.recipe.i18n = 0.5.0
+ z3c.recipe.eggbasket = 0.4.0
+ zc.buildout = 1.0.6
+ zc.recipe.egg = 1.1.0b1
+ zc.recipe.filestorage = 1.0.1
+ zc.recipe.testrunner = 1.0.0
+ zc.zodbrecipes = 0.4.0
+ zc.zope3recipes = 0.7.0
+
+ with::
+
+ # Here we pin the recipes and other packages that are not in the
+ # downloaded versions.cfg of grok
+ Paste = 1.7.2
+ PasteDeploy = 1.3.2
+ PasteScript = 1.7.3
+ setuptools = 0.6c9
+ z3c.evalexception = 2.0
+ z3c.recipe.eggbasket = 0.4.1
+ z3c.recipe.i18n = 0.5.0
+ z3c.recipe.template = 0.1
+ zc.buildout = 1.1.1
+ zc.recipe.egg = 1.1.0
+ zc.recipe.filestorage = 1.0.1
+ grokcore.startup = 0.2
+
+
+
+Upgrading already created projects
+----------------------------------
+
+`grokproject` received a lot of changes during releases. This also
+touched the structure of generated projects. For example there was
+support for paster_ introduced and the generation of configuration
+files changed heavily.
+
+Here we will explain, what changes were done (and why) and how you can
+apply those changes to your existing projects.
+
+
+Paster and `startup.py`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+With `grokproject` 1.0a1 we introduced paster_ support. This means,
+that the whole grok application is now by default served as a WSGI_
+application served by paster_.
+
+If your project has no `paster` script in ``bin/`` then you still lack
+paster support.
+
+To make paster support available in an existing project, follow these
+steps:
+
+1) Define entry points for paster, the ZDaemon controller and the debug
+ prompt.
+
+ In the `setup.py` of your project replace the (empty) entry points
+ definition (near end of file) by something like this::
+
+ entry_points = """
+ [paste.app_factory]
+ main = grokcore.startup:application_factory
+ """,
+
+ If you also want `ZDaemon` controlled starter scripts
+ (`bin/mypkg-ctl`, `bin/mypkg-debug`) add also the following entry
+ points for console scripts (they are not needed to run plain
+ paster) and read `Adding ZDaemon control scripts`_::
+
+ entry_points = """
+ [console_scripts]
+ <proj_mod_name>-debug = grokcore.startup:interactive_debug_prompt
+ <proj_mod_name>-ctl = grokcore.startup:zdaemon_controller
+ [paste.app_factory]
+ main = grokcore.startup:application_factory
+ """,
+
+ Please use the upper *or* the latter snippet, not both.
+
+ Make sure to replace ``<proj_mod_name>`` with the module name of
+ your project. This name equals to the directory name of the
+ directory holding your sources in ``src/``. So if you have a
+ directory ``src/myproj`` then the name will be ``myproj``. Normally
+ this is the lowercase version of your project name. Please note that
+ this name is case-sensitive.
+
+ The entry points we defined here can be used by certain buildout
+ recipes to generate scripts automatically. Note, that the
+ ``[console_scripts]`` are not necessary for paster but buildout to
+ create simple wrapper scripts for starting our application.
+
+ The entry points above determine, where other components (like
+ paster) can find certain python modules. For example we tell, that
+ there is a paster-compatible application factory available named
+ ``application_factory`` and placed in the ``grokcore.startup``
+ module. This module, of course, must be available during startup.
+
+ Let's care for this now.
+
+2) Require `grokcore.startup`.
+
+ Add an entry ``'grokcore.startup'`` to the list of
+ ``install_requires`` in your project's `setup.py`.
+
+ If you want your own/special WSGI configuration, then you can do so
+ and skip this step (see below for further details).
+
+3) Pin down versions of extra packages (optional).
+
+ To use paster we need some extra packages. The versions of those
+ packages can be pinned down in file ``versions.cfg`` or in a special
+ ``[versions]`` section of your `buildout.cfg`.
+
+ Add::
+
+ Paste = 1.7.2
+ PasteDeploy = 1.3.2
+ PasteScript = 1.7.3
+ z3c.evalexception = 2.0
+ grokcore.startup = 0.2
+
+ The version numbers pinned here are the ones used by latest
+ `grokproject` as time of writing (1.0a4). When you read this newer
+ versions might be in use.
+
+ You can remove (because we will not use it anymore)::
+
+ zc.zodbrecipes = 0.4.0
+ zc.zope3recipes = 0.7.0
+
+4) Create a separate `site.zcml` file.
+
+ When we use paster we also have to provide a separate `site.zcml`
+ file, as we have to refer to it in our paster configurations.
+
+5) Modify `buildout.cfg` to make the changes active.
+
+ Right now our modified project is likely to be broken. We have to
+ tell buildout that we like to have a paster-powered application.
+
+ * Remove ``zopectl`` from the ``parts`` in `buildout.cfg` (near
+ top).
+
+ Also remove the complete ``[zopectl]`` section from `buildout.cfg`
+ as we do not use it anymore (optional).
+
+ * In the ``[app]`` section of `buildout.cfg` copy the definition of
+ ``site.zcml`` (the one which consists of many lines) to a separate
+ file. We might need this later on.
+
+ * Replace the whole ``[app]`` section with the following::
+
+ [app]
+ recipe = zc.recipe.egg
+ eggs = <proj_egg_name>
+ z3c.evalexception>=2.0
+ Paste
+ PasteScript
+ PasteDeploy
+ interpreter = python-console
+
+ where instead ``<proj_egg_name>`` you should insert the name of
+ your project egg (as defined near top of `setup.py`). It is
+ normally the project name.
+
+ * Add a ``[log]`` section.
+
+ Add `log` to the list of parts near the beginning of
+ `buildout.cfg`.
+
+ Add the following somewhere in `buildout.cfg`::
+
+ [log]
+ recipe = zc.recipe.filestorage
+
+ This will generate a directory ``log/`` in the ``parts/``
+ directory of your project.
+
+6) Configuration files: templated or manually
+
+ From here we can go two distinct ways: we can generate the still
+ missing configuration files manually or go a quicker way by letting
+ buildout do it for us using templates.
+
+ If you prefer the latter, read on in section Setting up
+ configuration from templates below. This is also the recommended
+ approach as using templates for configuration you get configurations
+ usable in a version controlled environment (SVN or so) without
+ hardcoded paths.
+
+ Otherwise, or if you like to dig deeper into the details of
+ configuration, read on here.
+
+7) Create a `deploy.ini`
+
+ If we now rerun `bin/buildout`, there should be generated an
+ executable script `bin/paster`.
+
+ This, however, is not enough as we still need the configuration
+ files for our application to be served. We must tell paster where to
+ find the WSGI application and how it should be configured.
+
+ This is normally done in a file called `deploy.ini` or similar and
+ it can be very short::
+
+ # deploy.ini
+ [app:main]
+ use = egg:<proj_egg_name>
+
+ [server:main]
+ use = egg:Paste#http
+ host = 127.0.0.1
+ port = 8080
+
+ [DEFAULT]
+ # set the name of the zope.conf file
+ zope_conf = %(here)s/zope.conf
+
+ Again, replace ``<proj_egg_name>`` with the egg name of your
+ project.
+
+ This file can be placed where ever you like. Latest grokprojects
+ generate the file automatically from templates placed in ``etc/``
+ and write the generated file to ``parts/etc/deploy.ini``.
+
+
+8) Generate a `zope.conf`
+
+ As we can see in the `deploy.ini` above there is a reference to
+ another configuration file `zope.conf`. This is needed by the
+ application factory to configure the grok application we want to
+ serve.
+
+ Let's create a simple one::
+
+ # zope.conf
+ # Identify the component configuration used to define the site:
+ site-definition <project_path>/parts/etc/site.zcml
+
+ <zodb>
+ # Standard Filestorage
+ <filestorage>
+ path <proj_path>/parts/data/Data.fs
+ </filestorage>
+ </zodb>
+
+ <eventlog>
+ # This sets up logging to a file.
+ # The "path" setting can be a relative or absolute
+ # filesystem path.
+ <logfile>
+ path <proj_path>/parts/log/z3.log
+ formatter zope.exceptions.log.Formatter
+ </logfile>
+ </eventlog>
+
+ # Comment this line to disable developer mode. This should be done in
+ # production
+ devmode on
+
+ Of course, here we have to replace all ocurrences of ``<proj_path>``
+ with the absolute path to our project directory.
+
+ This file (`zope.conf`) has to be placed in the same directory as
+ `deploy.ini`.
+
+ Note, that the hardcoded absolute paths in here make it difficult to
+ use this configuration in a shared or version controlled development
+ environment. You can use templates (see below) to circumvent this.
+
+9) Create a `site.zcml`
+
+ The `zope.conf` contains a reference to a file called `site.zcml`,
+ where the configuration of the component architechture is stored
+ in. This file is also needed on startup, so we create a simple
+ `site.zcml`::
+
+ <configure xmlns="http://namespaces.zope.org/zope"
+ i18n_domain="MYPKG">
+
+ <include package="MYPKG" />
+ <configure i18n_domain="MYPKG">
+ <unauthenticatedPrincipal id="zope.anybody"
+ title="Unauthenticated User" />
+ <unauthenticatedGroup id="zope.Anybody"
+ title="Unauthenticated Users" />
+ <authenticatedGroup id="zope.Authenticated"
+ title="Authenticated Users" />
+ <everybodyGroup id="zope.Everybody"
+ title="All Users" />
+ <principal id="zope.manager"
+ title="Manager"
+ login="grok"
+ password_manager="SHA1"
+ password="e3756f86739bd029629243732eb682db005a7541f7509622"
+ />
+ <!-- Replace the following directive if you do not want
+ public access -->
+ <grant permission="zope.View"
+ principal="zope.Anybody" />
+ <grant permission="zope.app.dublincore.view"
+ principal="zope.Anybody" />
+
+ <role id="zope.Manager" title="Site Manager" />
+ <role id="zope.Member" title="Site Member" />
+ <grantAll role="zope.Manager" />
+ <grant role="zope.Manager"
+ principal="zope.manager" />
+ </configure>
+ </configure>
+
+ Please replace ``MYPKG`` with the name of your toplevel source
+ package, which is normally the lowercase projectname. In other
+ words: if your project contains a directory ``src/mypackage/`` then
+ replace ``MYPKG`` with ``mypackage`` in the above template.
+
+ The SHA1-hashed password above is ``grok`` in plain text (see also
+ "`Adding zpasswd script`_" below).
+
+ Put this file (`site.zcml`) at the location given in `zope.conf`
+ above.
+
+ Now you should be able to start paster. Try::
+
+ $ bin/paster serve deploy.ini
+
+ and if everything works okay, you should be able to browse
+ ``http://localhost:8080/``. The username/password with the
+ `site.zcml` configuration given above is ``grok`` and ``grok``.
+
+If you now also want ZDaemon controlled starter scripts (see step 1),
+read on below at `Adding ZDaemon control scripts`_.
+
+Defining your own WSGI configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _conftemplates:
+
+Configuration templates
+-----------------------
+
+With `grokproject` 1.0a3 we introduced generation of all main
+configuration files (`deploy.ini`, `debug.ini`, `zope.conf`,
+`site.zcml`, `zdeamon.conf`) via template files.
+
+The template files are by default put in the `etc/` directory of a
+freshly generated project and have the ``.in`` filename
+extension. They are read by a special recipe used by `buildout` and
+generate the real configuration files in the `parts/etc/` directory of
+your project when you run `buildout`. See
+`collective.recipe.template`_ for deeper insights.
+
+With the configuration templates enabled, `buildout` reads the
+configuration templates pointed to in `buildout.cfg`, expands any
+variables therein and writes the result to the real configuration
+files in `parts/etc/`.
+
+Using templates has a lot of advantages over manually writing
+configuration files. Most notably you can avoid hardcoded paths, so
+that the same configuration will work also on computers of other
+developers/users without changes.
+
+To make all this happen, you need the configuration file templates
+normally generated by `grokproject` and some new entries in
+`buildout.cfg`.
+
+We modify `buildout.cfg` so that the configuration files are looked up
+in the `etc/` subdirectory of our project. For each configuration file
+we give the template file and the location, where the resulting file
+should be created.
+
+Add the following sections to `buildout.cfg`::
+
+ [zope_conf]
+ recipe = collective.recipe.template
+ input = etc/zope.conf.in
+ output = ${buildout:parts-directory}/etc/zope.conf
+
+ [site_zcml]
+ recipe = collective.recipe.template
+ input = etc/site.zcml.in
+ output = ${buildout:parts-directory}/etc/site.zcml
+
+ [zdaemon_conf]
+ recipe = collective.recipe.template
+ input = etc/zdaemon.conf.in
+ output = ${buildout:parts-directory}/etc/zdaemon.conf
+
+ [deploy_ini]
+ recipe = collective.recipe.template
+ input = etc/deploy.ini.in
+ output = ${buildout:parts-directory}/etc/deploy.ini
+
+ [debug_ini]
+ recipe = collective.recipe.template
+ input = etc/debug.ini.in
+ output = ${buildout:parts-directory}/etc/debug.ini
+
+Each of these section names (``zope_conf``, ``site_zcml``, etc.) must
+also added to the list of ``parts`` near top of `buildout.cfg`, so
+that is might read similar to this::
+
+ parts = eggbasket app i18n test data log zpasswd
+ zope_conf site_zcml zdaemon_conf deploy_ini debug_ini
+
+Now all we need to make this work are the configuration file templates
+placed in an `etc/` subdirectory.
+
+Generating configuration templates using `grokproject`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the configuration files of your old project were not modified too
+heavily, you can easily generate all configuration files like this:
+
+1) Upgrade `grokproject` to the latest release (see above)::
+
+ $ easy_install -U grokproject
+
+2) Create a Grok project with the same projectname as the project you
+ want to upgrade::
+
+ $ grokproject Cave
+
+ Afterwards you have the complete bunch of configuration templates
+ in the `etc/` directory of your project.
+
+3) Copy the complete `etc/` directory of you freshly generated project
+ over to the old project:
+
+ $ cp -r Cave/etc old_proj/Cave/
+
+You might want to check, whether the settings in the configuration
+files (ports, passwords, etc.) meet your old project's settings.
+
+The configuration files hide in older projects somewhere in the
+`parts/` directory of your project.
+
+Please note that any terms like ``${buildout:directory}`` in template
+files are expanded when running buildout. Do not overwrite them with
+static absolute paths from your old configuration file unless you know
+what you are doing.
+
+If you rerun `buildout` afterwards, the new configuration files should
+be written to `parts/etc/` in your project.
+
+If you want to change the configuration files (not the templates),
+consider modifying the templates instead as on the next run of
+`buildout` your direct changes to files in `parts/` are likely to
+vanish while changes to the templates will go to the configuration
+files generated there.
+
+
+.. _findlinks:
+
+Using ``find-links``
+--------------------
+
+Some versions of `grokproject` generated an additional line in
+`buildout.cfg` saying::
+
+ find-links = http://download.zope.org/distribution/
+
+This line tells buildout to look for eggs not only in the standard
+Python PyPI (=Python Package Index, located at
+http://pypi.python.org/ ) but also in other locations like the Zope
+package index.
+
+The Zope PyPI was planned in the beginning as a pure mirror of the
+canonical Python PyPI, but was soon filled also with eggs not
+available at the standard PyPI. This means, that you still cannot get
+certain eggs from PyPI which are still hosted at the Zope site only.
+
+Furthermore the Zope PyPI was planned to serve as a fallback in case
+of outages of the central PyPI site and it should deliver eggs faster.
+
+Usage of ``find-links`` is quite common in the Zope2 and Plone world
+but it is meanwhile deprecated in the Zope 3 (aka ZTK, Zope Toolkit)
+world.
+
+As developers wanted to concentrate on a single repository shared with
+the whole Python community, all egg authors should now host their
+packages on http://pypi.python.org/ only.
+
+To enforce this usage pattern, people are strongly encouraged *not* to
+use the above `find-links` statement any more.
+
+Unfortunately, there is still a little number of eggs available from
+the Zope package index only, which also includes some eggs some
+`megrok` packages depend on. If you want this `megrok` packages to
+work (namely `megrok.form`), you have to lookup the Zope package index
+or in other words: you have to use the above `find-links` statement.
+
+As a rule of thumb you should try to cope without it. If, however, you
+get some errors during running `buildout` telling that some packages
+cannot be found, add the `find-links` statement.
+
+
+.. _zdaemon:
+
+Adding ZDaemon control scripts
+------------------------------
+
+To start a daemon that serves your grok application, all versions of
+`grokproject` generate a suitable script in the `bin/` directory.
+
+Recent versions of `grokproject` generate scripts in the `bin/`
+directory called `<proj-name>-ctl` and `<proj-name>-debug` where
+``<proj-name>`` is the lowercase project name.
+
+These scripts can be used like the well-known init-scripts on Unix
+systems. I.e. you can say something like::
+
+ $ ./bin/myproj-ctl start|stop|restart|fg|--help
+
+This is functionality actually provided by the `ZDaemon` software,
+also a part of the Zope software.
+
+In oldest versions, this script was called ``instance``.
+
+With introducing paster, the way of generating those scripts
+changed. So you have to care for this if upgrading.
+
+
+
+
+
+.. _zpasswd:
+
+Adding ``zpasswd`` script
+-------------------------
+
+You can add a ``zpasswd`` script (if you still lack one) by modifying
+the `buildout.cfg` in your project.
+
+1) Add ``zpasswd`` to the list of parts near top of the file.
+
+2) Add the following ``zpasswd`` section somewhere in `buildout.cfg`,
+ maybe at the end::
+
+ # This section is named so that the zpasswd utility is
+ # called `zpasswd`
+ [zpasswd]
+ recipe = z3c.recipe.dev:script
+ eggs = <proj_egg_name>
+ module = zope.app.server.zpasswd
+ method = main
+
+ Make sure to replace ``<proj_egg_name>`` by the name of your
+ project egg as set it ``setup.py`` (normally the project name).
+
+Rerun `bin/buildout` and the script should be generated.
+
+.. _collective.recipe.template:
+ http://pypi.python.org/pypi/collective.recipe.template
+
+.. _paster: http://pypi.python.org/pypi/Paste
+
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv
+
+.. _WSGI: http://www.wsgi.org/wsgi/
More information about the checkins
mailing list