A buildout recipe to install and configure OpenERP
This is a Buildout recipe that can download, install and configure one or several OpenERP servers, web clients, gtk clients and addons modules, from official or custom sources, or any bzr, hg, git or svn repositories. It currently supports versions 6.0, 6.1 and 7.0, with gunicorn deployment and an additional cron worker. It works under Linux and MacOs. It might work under Windows but it is untested.
For a quickstart you can jump to the howto section.
A “Buildout recipe” is the engine behind a Buildout “part”. A “buildout part” is a part of a larger application built with the Buildout sandbox build system. Using Buildout is harmless for your system because it is entirely self-contained in a single directory: just delete the directory and the buildout is gone. You never have to use administrative rights, except for build dependencies.
- Default options from zc.recipe.egg
- Specific options
- How to create and bootstrap a buildout
- Example OpenERP 6.1 buildout
- Example OpenERP 6.0 buildout
- Other sample buildouts
- 1.5.1 (27-02-2013)
- 1.5.0 (14-02-2013)
- 1.4 (16-01-2013)
- 1.3 (21-11-2012)
- 1.2.2 (11-11-2012)
- 1.2.1 (08-11-2012)
- 1.2 (07-11-2012)
- 1.1.5 (14-10-2012)
- 1.1.3 (26-09-2012)
- 1.0.3 (24-08-2012)
- 1.0 (24-08-2012)
- 0.17 (07-08-2012)
- 0.16 (29-06-2012)
- 0.15 (14-06-2012)
- 0.14.1 (17-05-2012)
- 0.14 (17-05-2012)
- 0.13.1 (14-05-2012)
- 0.13 (14-05-2012)
- 0.12 (02-05-2012)
- 0.11 (18-04-2012)
- 0.10 (02-04-2012)
- 0.9 (23-03-2012)
- 0.8 (20-12-2011)
- 0.7 (14-09-2011)
- 0.6 (11-09-2011)
- 0.5 (10-08-2011)
- 0.4 (09-08-2011)
- 0.3 (08-08-2011)
- 0.2 (08-08-2011)
- 0.1 (07-08-2011)
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
This recipe reuses the zc.recipe.egg:scripts recipe, so the options are the same (eggs, interpreter, etc.), and some changes, documented below.
Consult the documentation here http://pypi.python.org/pypi/zc.recipe.egg/1.3.2
The main useful ones are below:
Starting from version 0.16 of the recipe, you don’t need to put anything in this option by default. But you may specify additional eggs needed by addons, or just useful ones:
eggs = ipython openobject-library
The behaviour of this option is slightly modified : by default, no script other than those directly related to OpenERP 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 to not produce scripts):
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.
This is the default
interpreter option of
zc.recipe.egg that specifies the name
of the Python interpreter that shoud be included in the bin directory of the buildout:
interpreter = erp_python
The recipe also adds a few specific options:
Specifies the OpenERP version to use. It can be:
The version number of an official OpenERP (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
addons option (see below):
version = bzr lp:openobject-server/6.1 openerp61 last:1
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
Specifies additional OpenERP addons, either a local path or a repository.
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
When using local paths you can either specify a directory holding addons, or a single addon. In that latter case, it will be actually placed one directory below.
Never name one of these addons directory simply addons. It leads to obscure and blocking install errors for addons in other directories, claiming that some files don’t exist while they do.
For remote repositories, the syntax is:
TYPE URL DESTINATION REVISION [OPTIONS]
- TYPE can be bzr, hg, git or svn
- URL is any URL scheme supported by the versionning tool
- DESTINATION is the local directory that will be created (relative or absolute)
- REVISION is any version specification supported (revision, tag, etc.)
- 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.
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).
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).
OpenERP 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
script_name = start_erp
Specifies a delay in seconds to wait before actually launching OpenERP. 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
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 OpenERP 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).
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 OpenERP versions by tweaking options internally.
URL from which to download official and nightly versions (assuming the archive filenames are constistent with those in OpenERP download server). This is a basic mirroring capability:
base_url = http://download.example.com/openerp/
Allows to share OpenERP downloads among several buildouts. You should put this option in your ~/.buildout/default.cfg file. It specifies the destination download directory for OpenERP archives. The path may be absolute or relative to the buildout directory.
[buildout] openerp-downloads-directory = /home/user/.buildout/openerp-downloads
Gunicorn integration is only supported on OpenERP >= 6.1. Any value of this option makes the recipe generate a script to start OpenERP 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
For OpenERP 6.1, a special value of the gunicorn option is to be used if you plan to run Gunicorn behind a reverse proxy:
gunicorn = proxied
This behaviour has been kept for OpenERP >= 7 to keep backwards compatibility, but the option is now superseded by the general proxy_mode option of the server. In the buildout context, that’d be:
options.proxy_mode = True
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
The recipe sets the proper WSGI entry point according to OpenERP version, you may manually override that with an option:
gunicorn.entry_point = mypackage:wsgi.app
Finally, you can specify the Gunicorn script name with the gunicorn_script_name option. The configuration file will be named accordingly.
OpenERP 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. You may want to use the vcsdevelop extension to get it from Launchpad:
[buildout] extensions = gp.vcsdevelop vcs-extend-develop = bzr+http://bazaar.launchpad.net/openerp/openerp-command#egg=openerp-command
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.
Do not use to launch production servers, especially in an automatic way, openerp-command is really unstable and that may damage your installation.
This option is meant to produce an extension buildout configuration that effectively freezes the variable versions and revisions of the current configuration.
supported VCSes for this feature are currently Mercurial and Bazaar only.
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.
in DVCSes cases, nothing is done to check that the locally extracted revisions are actually pushed where they should.
Also, if the buildout configuration is itself under version control (a good practice), it is not in the recipe scope to commit or tag it. You are encouraged to use an external release script for that kind of purpose.
the recipe will also freeze python distributions installed with the gp.vcsdevelop extension but cannot currently protect against local modifications of these.
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 options 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.
You can define OpenERP options directly from the buildout file. The OpenERP
configuration files are generated by OpenERP itself in the
etc directory of
the buildout during the first Buildout run. You can overwrite these options
from the recipe section of your buildout.cfg. The options in the buildout
file must be written using a dotted notation prefixed with the name of the
corresponding section of the OpenERP config file. 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 natively exist in the openerp config file, it can be
created from there for your application.
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'
Note that for security reason, the superadmin password is not set by default. If you want to create a database you should temporary set it manually in the etc/openerp.conf file
To create a buildout and run the build, you just need 1 file and 2 commands:
- Create a single buildout.cfg file.
- Be sure you installed all your build dependencies
- Bootstrap the buildout with: python bootstrap.py
- Run the build with: bin/buildout
The same with more details below :
Create a buildout.cfg file in an empty directory, containing the configuration of the example 6.1 section.
You basically need typical development tools needed to build all the Python dependency eggs of OpenERP. You can do this by yourself with your system or Linux distribution.
Or if you’re using a Debian system, we provide a single dependency package you can use to install all dependencies in one shot:
Add the following line in your /etc/apt/sources.list:
deb http://apt.anybox.fr/openerp common main
Install the dependency package:
$ sudo aptitude update $ sudo aptitude install openerp-server-system-build-deps
You can uninstall this package with
aptitude after the build to
automatically remove all un-needed dependencies, but you need to
install run dependencies before that
$ sudo aptitude install openerp-server-system-run-deps $ sudo aptitude remove openerp-server-system-build-deps
Please note that these package will have your system install the client part of PostgreSQL software only. If you want a PostgreSQL server on the same host, that’s not in the recipe scope, just install it as well.
Bootstrapping the buildout consists in creating the basic structure of the buildout, and installing buildout itself in the directory.
The easiest and recommended way to bootstrap is to use a bootstrap.py script:
$ wget https://raw.github.com/buildout/buildout/master/bootstrap/bootstrap.py $ python bootstrap.py
As an alternative and more complicated solution, you may also bootstrap by creating a virtualenv, installing zc.buildout, then run the bootstrap:
$ virtualenv sandbox $ sandbox/bin/pip install zc.buildout $ sandbox/bin/buildout bootstrap
Here is a very simple example for a latest OpenERP 6.1 nightly and a custom addon hosted on Bitbucket:
[buildout] parts = openerp versions = versions find-links = http://download.gna.org/pychart/ [openerp] recipe = anybox.recipe.openerp:server # replace '6.1' with 'trunk' to get a 7.0 current nightly: version = nightly 6.1 latest addons = hg https://bitbucket.org/anybox/anytracker addons-at default [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
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.
Here is a sample buildout with version 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
Here are a few ready-to-use buildouts:
(Be sure to install system dependencies first)
OpenERP with the development branches of the Magento connector addons:
$ hg clone https://bitbucket.org/anybox/openerp_connect_magento_buildout $ cd openerp_connect_magento_buildout $ python bootstrap.py $ bin/buildout $ bin/start_openerp
OpenERP with the development branches of the Prestashop connector addons:
$ hg clone https://bitbucket.org/anybox/openerp_connect_prestashop_buildout $ cd openerp_connect_prestashop_buildout $ python bootstrap.py $ bin/buildout $ bin/start_openerp
- Christophe Combelles
- Georges Racinet
- Yannick Vaucher
The primary branch is on the launchpad:
Please don’t hesitate to give feedback and especially report bugs or ask for new features through launchpad at this URL: https://bugs.launchpad.net/anybox.recipe.openerp/+bugs
- launchpad #1130590: errors with inline comments such as freeze-to produces
- works with zc.buildout 2.0
- launchpad #1115503: now it’s possible to apply extract-downloads-to for a buildout configuration that uses the revisions option: the produced configuration resets revisions if needed.
- launchpad #1122015: soft requirements problem if offline on zc.buildout 2.0
- quality: now entirely flake8 compliant
- launchpad #1093771: extraction feature of downloaded code (notably vcs)
- launchpad #1068360: new ‘revisions’ option to fix VCS revisions separately
- launchpad #1093474: freeze feature of revisions and versions of python distributions
- launchpad #1084535: finer behaviour of with_devtools option: load testing hacks only in tests launcher script
- launchpad #1095645: missing devtools loading in openerp-command scripts
- launchpad #1096472: forbid standalone (single) local addons. A local addon must always be a directory that has addons inside.
- launchpad #1096472: trailing slash in a standalone addon directory name led to error.
- launchpad #1077048: fix gunicorn startup script for OpenERP 7
- launchpad #1079819: take into account newly introduced hard dependency to PIL in OpenERP 7
- launchpad #1055466: refactor version logic by providing major version tuple for comparisons.
- launchpad #1081039: introduced soft requirements and made openerp-command one of these.
- Nothing but fix of changelog RST
- Fixed an error in user feedback if openerp-command package is missing but needed
- launchpad #1073917: separated test command (bin/test_openerp)
- launchpad #1073127: support for openerp-command
- major improvement of test coverage in server recipe
- included buildout configurations for buildbotting of the recipe in source distribution
- Improved documentation (bootstrap and sample buildouts)
- Re-enabled support for trunk nightly (and maybe 7.0 final)
- fixed a packaging problem with openerp-cron-worker in 1.1.4
- launchpad #1041231: Resilience to changes of bzr locations
- launchpad #1049519: openerp-cron-worker startup script
- launchpad #1025144: By default, admin passwd is now disabled
- launchpad #1054667: Problem with current dev nightlies for OpenERP 6.2
- fixed a packaging problem with openerp-cron-worker in 1.1.2
- no actual difference with 1.0 (only changelogs and the like)
- launchpad #1040011: works with current OpenERP trunk (future 7.0)
- launchpad #1027994: ‘base_url’ option, to download from mirrors
- launchpad #1035978: restored ‘local’ version scheme for OpenERP itself. Also implemented the ‘url’ version scheme.
- removed deprecated renaming of 6.1 to 6.1-1
- Refactored the documentation
- launchpad #1033525: startup_delay option
- launchpad #1019888: Gunicorn integration.
- launchpad #1019886: installation of ‘openerp’ as a develop distribution, and full python server startup script.
- launchpad #1025617: Support for nightly versions in 6.1 series
- launchpad #1025620: Support for latest version
- launchpad #1034124: Fix interference of buildout options with gtkclient recipe
- launchpad #1021083: optional development tools loading in startup script
- launchpad #1020967: stop creating scripts by default
- launchpad #1027986: Better handling of interrupted downloads
- launchapd #1017252: relying on Pillow to provide PIL unless PIL is explicitely wanted.
- launchpad #1014066: lifted the prerequirement for Babel. Now the recipe installs it if needed before inspection of OpenERP’s setup.py
- launchpad #1008931: Mercurial pull don’t take URL changes into account. Now the recipe manages the repo-local hgrc [paths] section, updates the default paths while storing earlier values
- launchpad #1012899: Update problems with standalone vcs addons
- launchpad #1005509: Now bzr branches are stacked only if
- bzr-stacked-branches option is set to True.
- launchpad #1000352: fixed a concrete problem in Bzr reraising
- launchpad #1000352: option vcs-clear-retry to retrieve from scratch in case of diverged Bzr branches. Raising UpdateError in right place would trigger the same for other VCSes.
- Basic tests for Git and Svn
- Refactor with classes of VCS package
- launchpad #997107: fixed vcs-clear-locks option for bzr, that requires a user confirmation that cannot be bypassed in older versions
- launchpad #998404: more robust calls to hg and bzr (w/ unit tests), and have exception raised if vcs call failed (break early, break often).
- launchpad #997107: vcs-clear-locks option (currently interpreted by Bzr only)
- launchpad #993362: addons subdir option, and made repositories being one addon usable by creating an intermediate directory.
- Faster tarball inspection (see lp issue #984237)
- Shared downloads and more generally configurable downloads directory, see https://blueprints.launchpad.net/anybox.recipe.openerp/+spec/shared-downloads
- fixed the sample buildouts in the readme file
- Clean-up and refactoring
urloption (download url supported through
- Support OpenERP 6.1 and 6.0
- Added an ‘addons’ option allowing remote repositories and local directories
- Improved error messages
- Updated the documentation
- Handle bad Babel import in setup.py
- Support offline mode of buildout
- Create gtk client config without starting it
- handle deploying custom bzr branches
- handle new sections in openerp config
- Overwrite config files each time
- Make the “dsextras” error more explicit (install PyGObject and PyGTK)
- fixed some deps
- improved the doc
- Use dotted notation to add openerp options in the generated configs
- Added support for the web client and gtk client
- fixed config file creation
- Pass the trailing args to the startup script of the server
- Initial implementation for the OpenERP server only