anybox.recipe.openerp
=====================

.. contents::

This is a buildout recipe to download, install and configure OpenERP server,
web client and gtk client. It currently supports versions 6.0 and 6.1 and
custom branches. You get 3 recipes at once. The recipe to use is the following:

 - For the server: recipe = anybox.recipe.openerp:server
 - For the web client: recipe = anybox.recipe.openerp:webclient
 - For the gtk client: recipe = anybox.recipe.openerp:gtkclient

Recipe options
~~~~~~~~~~~~~~

zc.recipe.egg options
---------------------

This recipe reuses the *zc.recipe.egg:scripts* recipe, so the options
are the same (*eggs*, *interpreter*, etc.), with specific options, and
some changes, documented below.
Consult the documentation here http://pypi.python.org/pypi/zc.recipe.egg/1.3.2


New in version 0.16: the recipe takes care of all needed eggs for
OpenERP itself. The intended way to use the *eggs* option is to
provide extra dependencies that the additional addons may need.

Specific options
----------------

It also adds a few specific options :

 * **version**: specify one of:
   * the version number of an official OpenERP (server, web client or gtk client)
   * a custom download: `url http://example.com/openerp.tar.gz`
   * an absolute or a relative path: `path /my/path/to/a/custom/openerp`
   * the url of a custom bzr/hg/git/svn branch or repository. See *addons* below.
   The download area for official versions and custom downloads can be
   specified in the **openerp-downloads-directory** of the
   ``[buildout]`` section. Like all paths, if not absolute, it will be
   interpretated relatively to the buildout directory. By setting it in your
   ``default.cfg``, you may share the downloads among different
   buildouts.

 * **addons**: specify additional addons, either a path or a repository.
 * **script_name**: specify the name of the startup script to generate
 * **startup_delay**: specify a time in seconds to wait within the startup
   script before actually launching OpenERP. The Gunicorn startup script (see
   below) is not affected by this setting.
 * **with_devtools**: loads development and useful testing tools, such as
   ``anybox.testing.datetime``.

For the *version* and *addons* option, if you use a remote repository the syntax is::

  type url directory revision

where:
 * `type` can be bzr, hg, git or svn
 * `url` is any URL supported by the versionning tool
 * `directory` is the local directory that will be created
 * `revision` is any version specification supported

For the *addons* option, you can either specifiy a directory holding
addons, or a single one. In that latter case, it will be actually
placed one directory below

Changed options
---------------
Here are the options whose behaviour is different than the one from
``zc.recipe.eggs:scripts``:

 * `scripts`: by default, no script other than those directly related
   to OpenERP are generated are generated, but you may specify some
   explicitely, with the same semantics as the normal behaviour (we
   simply set an empty default value, which means not to produce scripts) :

        scripts = change_tz

   In the current state, beware *not* to require the same script in
   different parts or rename them. See
   https://bugs.launchpad.net/anybox.recipe.openerp/+bug/1020967 for details.

Official version
----------------

To use an official OpenERP version, just specify the version. For instance with the webclient::

    [webclient]
    recipe = anybox.recipe.openerp:webclient
    version = 6.0.3

Note: with OpenERP 6.1 the web client is natively included in the server as a simple module. In that case you don't need to write a separate part for the web client, unless that's what you really want to do.

Custom or development version
-----------------------------

If you want to use your own custom branch at revision 4751::

    [webclient]
    recipe = anybox.recipe.openerp:webclient
    version = bzr https://code.launchpad.net/~anybox/openobject-client-web/6.0-bug-906449 webclient-debug 4751

If you don't specify the revision, it will use the latest revision of
the branch.
The branch will be updated at each buildout run.


Custom addons
-------------

The `addons` option has a specific behaviour. You can use it to specify
additional OpenERP addons, either a relative or absolute path or
a specification for a version control system (VCS).

The first word of the value specifies the retrieval type (either
``local`` or a VCS short name). In the ``local`` case, the remainings
of the value is the path on the filesystem (relative to the buildout
directory or absolute).

In VCS cases, the syntax is uniformly::

  VCS_TYPE SOURCE_URL DESTINATION REVISION [OPTIONS]

Of these, URL and REVISION are interpreted by the prescribed VCS
system, while DESTINATION is an absolute path on the
filesystem, or relative to the buildout dir.

OPTIONS take the form ``name=value``. Currently, only the ``subdir``
option is recognized. If used, the given subdirectory of the
repository is registered as an addons directory.

The currently supported VCS types are bzr,hg,git and svn.

Example::

  addons = local ../some/relative/path/for/custom_addons/
           local /some/other/absolute/path/for/custom_addons
           bzr lp:openobject-addons/trunk/    addons0 last:1
           hg  http://example.com/some_addons addons1 default
           git http://example.com/some_addons addons2 master
           svn http://example.com/some_addons addons3 head
           bzr lp:openerp-web/trunk/ openerp-web last:1 subdir=addons

VCS sources are updated on each build according to the specified
revision. You have to be careful with the revision specification.

Buildout offline mode is supported. In that case, update to the
prescibed revision is performed, if the VCS allows it (Subversion does not).

OpenERP options
---------------
The OpenERP configuration files are generated by OpenERP itself in the buildout
`etc` directory during the first buildout run.  You can overwrite options in
these config files in the recipe section of your buildout.cfg.  The options
must be written using a dotted notation prefixed with the name of the section.
The specified options will just overwrite the existing options in the
corresponding config files. You don't have to replicate all the options in your
buildout.cfg.  If an option or a section does not exist in the openerp config
file, it can be created from there.

For example you can specify the xmlrpc port for the server or
even an additional option that does not exist in the default config file::

  options.xmlrpc_port = 8069
  options.additional_option = "foobar"

It will end-up in the server config as::

  [options]
  xmlrpc_port = 8069
  additional_option = "foobar"

For the web client you can specify the company url with::

  global.server.socket_port = 8080
  openerp-web.company.url = 'http://anybox.fr'

It will modify the corresponding web client config::

  [global]
  server.socket_port = 8080

  [openerp-web]
  company.url = 'http://anybox.fr'

Generated startup scripts
-------------------------

Startup scripts are created in the `bin` directory. By default the name is:
start_<part_name>, so you can have several startup scripts for each part if you
configure several OpenERP servers or clients. You can pass additional typical
arguments to the server via the startup script, such as -i or -u options.
You can choose another name for the script by using the *script_name*
option.

Gunicorn integration (OpenERP >= 6.1 only)
------------------------------------------
If you add a ``gunicorn`` option with value ``direct`` or ``proxied``,
you'll also get for OpenERP >= 6.1 a script named
``gunicorn_<part_name>`` to serve your OpeneERP part right away with
the Gunicorn WSGI server.

Use ``proxied`` if you plan to run Gunicorn behind a reverse proxy.

Gunicorn-specific options are to be specified with the ``gunicorn.``
prefix and will end up in the the Gunicorn python configuration file
``etc/gunicorn_<part_name>.conf.py``, such as::

  gunicorn.workers = 8

If you don't specify ``gunicorn.bind``, then a value is constructed
from the relevant options for the OpenERP script (currently
``options.xmlrpc_port`` and ``options.xmlrpc_interface``).
Other supported options and their default values are::

  gunicorn.workers = 4
  gunicorn.timeout = 240
  gunicorn.max_requests = 2000

Finally, you can specify the Gunicorn script name with the
``gunicorn_script_name`` option. The configuration file will be named
accordingly.

Example OpenERP 6.0 buildout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here is a sample buildout with versions specification, 2 OpenERP servers (with
one using the latest 6.0 branch on the launchpad) using only NETRPC and
listening on 2 different ports, and 2 web clients::

    [buildout]
    parts = openerp1 web1 openerp2 web2
    #allow-picked-versions = false
    versions = versions
    find-links = http://download.gna.org/pychart/
    
    [openerp1]
    recipe = anybox.recipe.openerp:server
    version = 6.0.3
    options.xmlrpc = False
    options.xmlrpcs = False
    
    [web1]
    recipe = anybox.recipe.openerp:webclient
    version = 6.0.3
    
    [openerp2]
    recipe = anybox.recipe.openerp:server
    version = bzr lp:openobject-server/6.0 openobject-server-6.x last:1

    options.xmlrpc = False
    options.xmlrpcs = False
    options.netrpc_port = 8170
    
    [web2]
    recipe = anybox.recipe.openerp:webclient
    version = 6.0.3
    global.openerp.server.port = '8170'
    global.server.socket_port = 8180
    
    [versions]
    MarkupSafe = 0.15
    Pillow = 1.7.7
    anybox.recipe.openerp = 0.9
    caldav = 0.1.10
    collective.recipe.cmd = 0.5
    coverage = 3.5
    distribute = 0.6.25
    feedparser = 5.0.1
    lxml = 2.1.5
    mako = 0.4.2
    nose = 1.1.2
    psycopg2 = 2.4.2
    pychart = 1.39
    pydot = 1.0.25
    pyparsing = 1.5.6
    python-dateutil = 1.5
    pytz = 2012b
    pywebdav = 0.9.4.1
    pyyaml = 3.10
    reportlab = 2.5
    vobject = 0.8.1c
    z3c.recipe.scripts = 1.0.1
    zc.buildout = 1.5.2
    zc.recipe.egg = 1.3.2
    Babel = 0.9.6
    FormEncode = 1.2.4
    simplejson = 2.1.6


Example OpenERP 6.1 buildout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here is a simple example for a stock OpenERP 6.1, with a GTK client, and a
local addon you are developping for a client project::

    [buildout]
    parts = openerp gtk
    #allow-picked-versions = false
    versions = versions
    find-links = http://download.gna.org/pychart/
    
    [openerp]
    recipe = anybox.recipe.openerp:server
    version = 6.1-1
    addons = local ../path/to/my/local/addons

    options.xmlrpcs = False

    gunicorn = direct

    [gtk]
    recipe = anybox.recipe.openerp:gtkclient
    version = 6.1-1
    
    [versions]
    MarkupSafe = 0.15
    Pillow = 1.7.7
    PyXML = 0.8.4
    babel = 0.9.6
    feedparser = 5.1.1
    gdata = 2.0.16
    lxml = 2.3.3
    mako = 0.6.2
    psycopg2 = 2.4.4
    pychart = 1.39
    pydot = 1.0.28
    pyparsing = 1.5.6
    python-dateutil = 1.5
    python-ldap = 2.4.9
    python-openid = 2.2.5
    pytz = 2012b
    pywebdav = 0.9.4.1
    pyyaml = 3.10
    reportlab = 2.5
    simplejson = 2.4.0
    vatnumber = 1.0
    vobject = 0.8.1c
    werkzeug = 0.8.3
    xlwt = 0.7.3
    zc.buildout = 1.5.2
    zc.recipe.egg = 1.3.2
    zsi = 2.0-rc3

Contribute
~~~~~~~~~~
Author and contributors:

 * Christophe Combelles
 * Georges Racinet

The primary branch is on the launchpad:

 * Code repository and bug tracker: https://launchpad.net/anybox.recipe.openerp
 * PyPI page: http://pypi.python.org/pypi/anybox.recipe.openerp

Please don't hesitate to give feedback and especially report bugs or
ask for new features through launchpad.
