Configuration reference¶

Command line¶

The configuration file can be specified from the command line:

bin/buildout -c buildout.local.cfg

Recipe options can be overridden from the command-line:

bin/buildout -c buildout.local.cfg openerp:clean=True openerp:xmlrpc_port=8169

Parts that are not listed in the buildout configuration section can be explicitely installed:

bin/buildout install openerp funkload static-analysis

Inheritance¶

A buildout configuration file can reference another one and change some options (note the += notation that’s not part of the INI format):

[buildout]
extends = buildout.base.cfg

[openerp]
eggs += nose
        coverage
with_devtools = True

These extensions can be chained. This allows in particular project maintainers to separate the configuration options that are considered to be part of the project from those that depend on the server environment (ports, database hosts…)

Default configuration¶

If available, the settings from $HOME/.buildout/default.cfg always apply, as if it where the default value of the extends option.

This is commonly used with the eggs-directory and openerp-downloads-directory options, because these amount to create a user-level cache.

Finally, you may also use extends in default.cfg to point to a system-wide configuration file (useful to enforce policies at the organization or physical site level, such as local index servers, mirrors, etc.).

Server¶

recipe = anybox.recipe.openerp:server

recipe = anybox.recipe.openerp[bzr]:server

Web client¶

recipe = anybox.recipe.openerp:webclient

GTK client¶

recipe = anybox.recipe.openerp:gtkclient

version¶

Specifies the Odoo version to use. It can be:

• The version number of an official Odoo (server, web client or gtk client):

  version = 6.0.3
  

• A custom download:

  version = url http://example.com/openerp.tar.gz
  

• An absolute or a relative path:

  version = path /my/path/to/a/custom/openerp
  

• A custom bzr, hg, git or svn branch or repository. The syntax is the same as with the addons option:

  recipe = anybox.recipe.openerp[bzr]:server
  version = bzr lp:openobject-server/6.1 openerp61 last:1
  

  Note

  the [bzr] extra dependency declaration is useful for resolution of the lp: address shortcuts.

• A nightly build:

  version = nightly 6.1 20120814-233345
  

• or (dangerously unpinned version):

  version = nightly 6.1 latest
  

• or even more dangerous:

  version = nightly trunk latest
  

addons¶

Specifies additional Odoo addons, either a local path or a remote repository.

Example:

recipe = anybox.recipe.openerp[bzr]:server
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

Remote repositories can either contain addons subdirectories, or be a single addon. In that latter case, called a standalone addon, the group option must be used to place the addon in an intermediate subdirectory, to match the structure expected by Odoo.

Standalone addons are not supported in the local case (the directory is considered under full responsibility of the user).

For remote repositories, the syntax is:

TYPE  URL  DESTINATION  REVISION  [OPTIONS]

with the following semantics:

Repositories are updated on each build according to the specified revision. You must be careful with the revision specification.

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

git http://example.com/some_addons some/target_dir group=some_group

bzr lp:openerp-web/7.0 openerp-web last:1 subdir=addons

version = git http://github.com/odoo/odoo.git odoo 8.0 depth=1

version = git http://github.com/odoo/odoo.git odoo 8.0 depth=None

merges¶

Specify which VCS branches need to be merged into repositories specified under addons or version. The syntax is the same as for repositories specified under these directives.

Currently only merges on bzr and git repositories are supported (requires git 1.8)

eggs¶

This option behaves like the identically named one of the most common zc.recipe.egg.

Starting from version 0.16 of the recipe, you don’t need to put anything in this option by default: the recipe is supposed to add all needed dependencies for Odoo by itself, but you have to specify additional eggs needed by addons, or just useful ones:

eggs = ipython
       python-ldap
       openobject-library

apply-requirements-file¶

Default value: False

If set to True, this boolean option makes the recipe read Odoo’s requirements.txt file if available, and apply its prescriptions.

revisions¶

This option allows to further precise what has been specified through the addons and version options by fixing VCS revisions.

The main use-case it to apply it in an extension buildout configuration file:

[buildout]
extends = base.cfg

[openerp]
revisions = 4320  ; main software
            addons-openerp 7109

As you can see in that example, the first token is the target filesystem path, as in the addons option, the second one is the revision, except in the case of the main software (if VCS based), for which there’s no filesystem path.

Some interesting use-cases:

• temporary fixing some revision in cas of upstream regression with no impact on your main development configuration (no risk to commit an unwanted freeze if the main configuration is itself versionned).
• freezing satisfactory revisions in a release process (the recipe can do that automatically for you, see freeze-to option below).

clean¶

If set to true, this option will clean remove python object files from the main server part and addons before any update or install, and perform relevant VCS idea of “clean, purge”.

Note that tarball downloads get re-extracted afresh in any case.

vcs-revert¶

Possible value: on-merge (more are been thought of)

If this option is used with the on-merge value, the VCS repositories will be reverted, losing all local modifications after the pull/update, right before the merge.

This is especially useful in unattended executions, to clean up any previous failed merges.

Currently only bzr and git repositories get reverted.

vcs-clear-retry¶

If True failed updates are cleared and retried once. This is intended for brittle VCSes from CI robots.

vcs-clear-locks¶

Some VCS systems can leave locks after some failures and provide a separate way to break them. If True,the repo will break any locks prior to operations (mostly useful for automated agents, such as CI robots)

git-depth¶

This is the global variant of the The depth Git option option (please read the provisions there carefully, as it is potentially dangerous).

Setting a value to git-depth is the same as doing it for all involved Git repositories, but does not have precedence over per-repository settings (which can also remove it altogether).

This option is especially meant for automated tools (continuous integration, unattended deployment) as they can easily add it from the command-line to any buildout.

script_name¶

Odoo 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 Odoo 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

script_name = start_erp

gevent_script_name¶

..note :: for Odoo version 8 and onwards

Lets you control the name of the asynchronous longpolling listener leveraging gevent (known as openerp-gevent in the basic install).

The default is gevent_<PART>.

openerp_scripts¶

This option lets you install console scripts provided by any of the loaded eggs, so that they can access to Odoo internals and load databases.

Here we describe the format of the option only. For explanation about what it means and how to use it, please refer to Odoo Scripts.

The option is multiline. Each line specifies exactly one script, and must respect the following format:

ENTRY_POINT_NAME[=WISHED_SCRIPT_NAME] [MODIFIER [MODIFIER […]]]

Each modifier takes the MODIFIER_NAME=MODIFIER_VALUE form. No whitespace is allowed in modifiers, entry point, nor produced script names.

Here’s the list of currently available modifiers, with links inside the dedicated chapter about Odoo scripts).

Full example:

openerp_scripts = my_script arguments=session
                  my_other_script=actual-script-name arguments=3,session
                  nosetests=nosetests command-line-options=-d
                  sphinx-build=sphinx-build openerp-log-level=ERROR command-line-options=-d

upgrade_script_name¶

This option lets you specify the wished name for the upgrade script. The default value is upgrade_<part_name>.

upgrade_script¶

This option lets you specify a source (.py) file and a callable defined in that file to perform database upgrades. The default value is:

upgrade_script = upgrade.py run

If the specified source file doest not exist, the recipe will initialize it with a simple and meaningful sample content, consistent with the default value above.

If you want not to have an upgrade script, just override this option with a blank value:

upgrade_script =

See the full Upgrade scripts documentation to learn more about upgrade scripts.

gunicorn¶

Gunicorn integration is only supported on Odoo ≥ 6.1. Any value of this option makes the recipe generate a script to start Odoo with Gunicorn and (new in version 1.1) a dedicated script to handle cron jobs.

For OpenERP 6.1, the only accepted values are direct and proxied. Any value is suitable for OpenERP ≥ 7

gunicorn = proxied

options.proxy_mode = True

gunicorn.workers = 8

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

gunicorn.entry_point = mypackage:wsgi.app

server_wide_modules¶

This multi-line option lets you specify addons to be loaded directly at startup, independently of what is installed in the database.

It plays the same role as the --load command-line option of the main Odoo startup script, with lower precedence if the latter is also specified. Examples:

server_wide_modules = custom_homepage

Since there is no entry in the Odoo configuration file corresponding to --load, this recipe option helps bringing uniformity accross running instances of the project by enclosing this notion in the shippable configuration.

It can also be leveraged by other scripts or recipe subsystems, notably the gunicorn startup script.

openerp_command_name¶

Odoo Command Line Tools (openerp-command for short) is an alternative set of command-line tools that may someday subsede the current monolithic startup script. Currently experimental, but already very useful in development mode.

It is currently enabled if the with_devtools option is on.

This works by requiring the openerp-command python distribution, which is not on PyPI as of this writting, but comes bundled with the current Odoo trunk (believed to be the future Odoo 8).

As for other scripts, you can control its name of the produced script, e.g:

openerp_command_name = oe

the name defaults otherwise to <part_name>_command. Note that oe is the classical name for this script outside of the realm of this buildout recipe.

[buildout]
extensions = gp.vcsdevelop
vcs-extend-develop = bzr+http://bazaar.launchpad.net/~openerp/openerp-command/7.0#egg=openerp-command

scripts¶

This option controls the generation of console scripts declared by the various involved Python distributions (either directly required with the eggs option, or by dependency).

By default, no such script is generated, but you may specify some according to your needs, with the same semantics as in zc.recipe.egg.

scripts = change_tz

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

startup_delay¶

Specifies a delay in seconds to wait before actually launching Odoo. This option was a preliminary hack to support both gunicorn instance and a legacy instance. The Gunicorn startup script (see below) itself is not affected by this setting

startup_delay = 3

with_devtools¶

Allows to load development and install useful devlopment and testing tools, notably the following scripts:

• test_openerp: a uniform test launcher for all supported versions. See test_script_name option below for details.
• openerp_command: see openerp_command_name option below for details. Not installed for Odoo major versions less than or equal to 6.1.

This option is False by default, hence it’s activated this way:

with_devtools = true

It will also add some dependencies that are typical to development setups (tests related packages etc.) and automatically load where needed helpers, such as anybox.testing.datetime (allows to cheat with system time).

test_script_name¶

If the with_devtools is set to True, the recipe will create a test script, which is named by default test_<part_name>. You may override the name in the configuration as in the following example:

test_script_name = test_erp

The test script takes the same arguments as the regular startup script:

bin/test_openerp --help
bin/test_openerp -d test_db -i purchase,sale

At the time of this writing, all this script does compared to the regular startup script is to bring uniformity across Odoo versions by tweaking options internally.

As of version 1.8.2, the --install-all additional option will be expanded on-the-fly as -i on all available modules (don’t confuse with -i all: the latter is equivalent to -i base).

interpreter_name¶

The recipe will automatically create a python interpreter with a session object that can bootstrap Odoo with a database right away. You can use that for interactive sessions or to launch a script:

$ bin/python_odoo
To start the Odoo working session, just do:
    session.open(db=DATABASE_NAME)
or, to use the database from the buildout part config:
    session.open()
All other options from buildout part config do apply.
Then you can issue commands such as:
    session.registry('res.users').browse(session.cr, 1, 1)
Or using new api:
    session.env['res.users'].browse(1)
>>>

The interpreter name is python_<part_name> by default; but it can be explicitely set like this:

interpreter_name = my_py

If you want not to have the interpreter, juste do

interpreter_name =

If you want to wrap a python script with such session objects you need to use the openerp_scripts option. See Odoo Scripts and especially Arguments and session.

If you want a more comfortable Python console like IPython or bPython, take a look at Interactive Consoles.

interpreter¶

With the gtkclient and webclient recipes, this behaves like the interpreter option of zc.recipe.egg: it gives you a Python interpreter in the bin subdirectory of the buildout:

interpreter = erp_python

With the server recipe, the interpreter option will be ignored, because this recipe always creates an interpreter with preloaded objects to bootstrap openerp, and these depend on the configuration. Check interpreter_name for more details.

base_url¶

This option is local to the part.

URL from which to download official and nightly versions (assuming the archive filenames are constistent with those in Odoo download server). This is a basic mirroring capability:

base_url = http://download.example.com/openerp/

openerp-downloads-directory¶

This is an option for the [buildout] section

Allows to share Odoo downloads among several buildouts. You should put this option in your ~/.buildout/default.cfg file. It specifies the destination download directory for Odoo archives. The path may be absolute or relative to the buildout directory.

Example:

[buildout]
openerp-downloads-directory = /home/user/.buildout/openerp-downloads

freeze-to¶

This option is meant to produce an extension buildout configuration that effectively freezes the variable versions and revisions of the current configuration.

It is meant for release processes, and as such includes some consistency checks to avoid as much as possible issuing a frozen configuration that could be different from what the developper or release manager is assumed to have just tested. Namely:

• it works only in offline mode (command-line -o flag). This is to avoid fetching new revisions from VCSes or PyPI
• it fails if some VCS-controlled addons or main software have local modifications, including pending merges.

The recommended way to use it is through the command line (all buildout options can be set this way). Here’s an example, assuming the part is called openerp-server-1:

bin/buildout -o openerp-server-1:freeze-to=frozen.cfg

This produces a buildout configuration file named frozen.cfg, with notably an openerp-server-1 part having a revisions option that freezes everything.

For configurations with several openerp related parts, you can freeze them together or in different files. This gives you flexibility in the distributions you may want to produce from a single configuration file:

bin/buildout -o openerp-server-1:freeze-to=server.cfg openerp-server-2:freeze-to=server.cfg gtkclient:freeze-to=client.cfg

In that latter example, server.cfg will have the two server parts, while client.cfg will have the gtkclient part only.

freeze-allow-picked-versions¶

This option is to be used in conjunction with freeze-to. If set to False, it will add allow-picked-versions = false for zc.buildout versions that support this flag.

extract-downloads-to¶

Following the same kind of logic as freeze-to, this option allows to turn a buildout that aggregates from various remote sources (tarball downloads, VCSes) into a self-contained buildout archive directory that can be packed for easy distribution.

Actually it extracts only the downloaded elements into a target directory and issues a buildout configuration with local references only. If that target directory has been itself initialized first with the fixed elements (buildout configuration files, bootstrap scripts, local addons), then it has all the needed elements, except eggs to be downloaded from PyPI or the specified index site.

Here is an example, assuming the fixed elements are themselves versioned with Mercurial:

hg archive ../test-extract && bin/buildout -o openerp:extract-downloads-to=../test-extract

The produced buildout configuration in the target directory is release.cfg. So, for instance, from our test-extract archive, the buildout can be executed like this:

python bootstrap.py && bin/buildout -c release.cfg

or further extended for system-dependent options such as port, db connection, etc.

The extract-downloads-to option can be used for several parts with the same target directory (same as freeze-to).

Furthermore, a default freeze-to is issued, producing a buildout configuration called extracted_from.cfg in the target directory, for later reference (local modification tracking) or a more developper-friendly reproduction configuration (ready-made setup to derive bugfix branches from).

This implication of freeze-to also has the side effect to enforce the same rules with respect to uncommitted changes.

Python distributions managed with gp.vcsdevelop are taken into account.